Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs: align contribution and bot review with change impact (#346)
tt-a1idaced37a66ab
diff --git a/.coderabbit.yaml b/.coderabbit.yamlindex a3ba9623..f6972c2a 100644--- a/.coderabbit.yaml+++ b/.coderabbit.yaml@@ -15,7 +15,9 @@ reviews:Distinguish author-reported validation from observed checks at the currenthead. Do not claim browser or perceptual acceptance from static tests.poem: false+ in_progress_fortune: falsesequence_diagrams: false+ assess_linked_issues: falsesuggested_labels: falsesuggested_reviewers: falseauto_review:@@ -35,7 +37,7 @@ 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 proportionallyto the actual behavior changed. Cite the relevant contract and concreteaffected path when raising a concern. Reuse explicit maintainer scopedecisions; do not demand a new issue for a small documentation correction@@ -43,6 +45,13 @@ reviews:as proposed changes, not authority to waive the base branch's rules.Review authoritative source before generated output. Do not requestunrelated 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 scopemode: warninginstructions: >-- Read CONTRIBUTING.md and .github/PULL_REQUEST_TEMPLATE.md. Pass when+ Read CONTRIBUTING.md, REVIEWING.md, and .github/PULL_REQUEST_TEMPLATE.md. Pass whenthe PR explains the user problem, one focused behavior or deliveryslice, 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. Acceptequivalent prose and explained Not applicable entries, not just exactheadings 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 claimsneed comparable conditions. Automated/browser and perceptual resultsmust 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 smallestmissing evidence set. Do not require screenshots for non-visual changesor infer a browser pass from a unit test. Accept explicit maintainerexceptions 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: truefilePatterns:- CONTRIBUTING.md+ - REVIEWING.md- .github/PULL_REQUEST_TEMPLATE.md- archify/references/delivery-contract.mdlearnings:diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.mdindex e0d5ad09..9ea43cef 100644--- a/.github/PULL_REQUEST_TEMPLATE.md+++ b/.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.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex bd6ce500..69dc7b92 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,105 +1,85 @@# Contributing to Archify-Thank you for helping Archify make engineering diagrams more trustworthy and useful. Archify is Agent-first: people describe the system they want to explain, while the Skill, typed JSON contract, renderers, validators, and delivery receipts make the result reproducible.--Stability comes before feature count. A small change with a real reproduction, an explicit contract, and evidence from the final artifact is easier to review and safer to ship than a broad rewrite.+Archify is Agent-first: people describe systems, and the Skill, typed JSON, renderers, validators, and delivery receipts produce reproducible diagrams. Keep each contribution focused on one user-visible behavior or one tightly related delivery slice. Maintainers and Agents reviewing a PR or a revised head follow [Reviewing](REVIEWING.md).## Choose the right path-- Found a renderer, validator, package, or viewer problem? Use [the bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).-- Made a useful real-world diagram? Use [the showcase form](.github/ISSUE_TEMPLATE/showcase.yml).-- Want to change a schema, renderer contract, validation rule, installation path, export, or other product behavior? Open or link an issue before implementing it. Agree on the user value, compatibility boundary, and non-goals first.-- Found a security vulnerability? Follow [the security policy](SECURITY.md). Do not publish exploit details or secrets.+- Renderer, validator, package, or Viewer defect: use the [bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).+- Reproducible real-world diagram: use the [showcase form](.github/ISSUE_TEMPLATE/showcase.yml).+- New schema fields, defaults, acceptance rules, installation/export contracts, or broad product behavior: agree on value, compatibility, and non-goals before substantial implementation. Link the issue or recorded maintainer decision; reuse an existing agreed scope.+- Narrow fixes and small documentation or test corrections can proceed with a concrete reproduction or rationale; a separate planning issue is unnecessary.+- Security vulnerabilities: follow [SECURITY.md](SECURITY.md).-Small documentation corrections and narrowly scoped test fixes do not require a planning issue. Large documentation surfaces do: prefer improving the canonical Skill, contract, diagnostic, or existing guide over creating a second explanation of the same behavior.+Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in fixtures, logs, screenshots, artifacts, or package tests.-Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in prompts, JSON fixtures, logs, screenshots, generated artifacts, or package tests.+## Prepare a reviewable change-## Before writing code+Start from the latest `main`. Check whether its existing controls already solve the reported case. Record the comparison base and candidate head.-Start from the latest `main`. Recheck it before final review: a concurrent change may already solve the problem or alter the relevant contract. A test result from an old base is not integration evidence.+Use Draft for unresolved scope or early implementation feedback. At this stage, provide the smallest reproduction and relevant checks. Prepare broad integration evidence and generated artifacts once the approach is settled.-Keep one pull request focused on one behavior or one tightly related delivery slice. The PR should state:+Before requesting final review, explain:-- the user problem and linked issue, when one exists;-- what changes and what deliberately does not;-- compatibility and migration impact;-- failure behavior and rollback path;-- exact tests and final-artifact evidence.+- The current-main trigger, intended outcome, and why the approach is worth maintaining.+- The changed behavior and shared callers, existing behavior that must remain stable, and any intended compatibility changes.+- The applicable checks, actual results, and reproducible evidence links.-Draft PRs are welcome for early technical feedback. Mark the PR ready only when its scope is stable, it is current with `main`, its generated artifacts are intentional, and the stated checks have actually run.+Use [the PR template](.github/PULL_REQUEST_TEMPLATE.md); link existing receipts or CI output instead of transcribing long logs. Classify impact by behavior and callers, not file extension or diff size.-## Product and compatibility contracts+## Choose evidence by impact-Archify's public behavior is larger than a renderer function. Treat these as contracts:+| Impact | Typical change | Evidence to prepare |+| --- | --- | --- |+| Text or review policy | Explanatory prose, links, contributor/reviewer procedure | Content, links, affected documentation checks; exercise changed procedure branches. No local renderer suite for repository-only prose. |+| Local behavior | One CLI path, focused test correction | Reproduction or rationale, affected tests, and relevant failure/compatibility cases. |+| Shared behavior | Geometry, text measurement, shared Viewer, evidence or delivery helpers | Trace callers; identify affected modes and contracts; compare fixed representative inputs on base and candidate, including relevant historical failures. |+| Contract change | Schema, defaults, validation acceptance, Skill or authoring instructions | Agreed scope and explicit allowed/preserved behavior, plus local/shared evidence appropriate to the implementation. |-- Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.-- Explicit authored geometry such as `via`, named routes, channels, sides, and label placement remains authoritative unless the contract says otherwise. Do not silently rewrite topology or authored intent.-- `standard` preserves broad compatibility. A new `showcase` failure must identify a real, repairable defect, avoid rejecting necessary routing, and return a stable machine-readable diagnostic.-- Agent-facing failures belong in `diagnostics[]`: use a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`. Do not require ordinary users or Agents to scrape prose from logs.-- Agent-first does not mean documentation-free. It means one canonical contract per behavior. Link to that source instead of copying evolving CLI stages, receipt fields, or error-code tables into parallel manuals.-- A valid SVG is not automatically a good diagram. Geometry, projected text, z-order, masks, interaction, export, and real browser layout can fail independently.+Skill instructions, authored examples, build inputs, and generated-site sources are behavioral inputs even when they look like documentation. Policy changes need process review; runtime evidence depends on whether they affect runtime inputs.++During iteration, run the narrowest relevant checks. Before final review, run `npm test` from `archify/` for changes to runtime, schemas, packaged Skill/authoring behavior, generated content, or shared test infrastructure. Repository-only documentation and focused test-only changes may use targeted checks with an explanation. These local choices do not waive remote CI or branch-protection requirements.++## Product and compatibility contracts-If a validation rule expresses taste rather than correctness, begin with evidence or a warning. Before making it a hard error, test legitimate exceptions such as obstacles, shared ports, explicit routing, nested boundaries, and existing checked-in examples.+- Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.+- Explicit authored geometry such as `via`, named routes, channels, sides, and label placement remains authoritative unless the contract says otherwise. Preserve authored topology and intent.+- `standard` preserves broad compatibility. A new `showcase` failure must identify a real, repairable defect and avoid rejecting necessary routing.+- Agent-facing failures belong in `diagnostics[]`: use a stable `code`, precise `subject`, concrete `evidence`, and executable `supportedFixes`. Preserve non-zero CLI exits and machine-readable receipts for failed stages.+- A validation rule expressing taste should begin with evidence or a warning. Before making it a hard error, check legitimate obstacles, shared ports, explicit routes, nested boundaries, and existing examples.+- Keep one canonical contract per behavior. Link the existing source instead of copying CLI stages, receipt fields, or error tables.-## Local setup+## Local setup and verification-The renderer package lives in `archify/` and supports Node.js 18 and later. CI covers Node.js 18, 20, 22, and 24.+The renderer package is in `archify/`; its Node range and commands are defined in `archify/package.json`.-```bash+```shcd archifynpm cinpm test```-During development, run the narrowest relevant test first, then the full suite before requesting final review. Behavioral fixes should include a failing regression test that demonstrates the problem before the implementation changes.--Test public behavior through a supported seam whenever possible: `archify render`, `validate`, `deliver`, `visual-check`, or the final SVG/HTML. Private helper tests are useful for edge cases, but they do not replace a CLI or artifact-level regression.--## Evidence by change type+Test through public behavior such as `render`, `validate`, `deliver`, `visual-check`, or final SVG/HTML. Behavioral fixes should include a regression that demonstrates the original failure. Private helper checks can supplement that evidence.-### Renderer, layout, and validation+For geometry and layout changes, use the smallest redacted JSON reproduction, relevant checked-in examples, and frozen compatibility fixtures. Compare base and candidate with the same input and browser conditions. Identify intended changes and investigate unexpected ones; updating golden files alone does not establish visual or compatibility acceptance.-Include the smallest redacted typed JSON that reproduces the behavior. Verify both the intended fix and plausible exceptions. At minimum:+A visual PR must provide enough evidence to evaluate whether the intended user value was achieved, using screenshots, recordings, or reproducible steps. Keep viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review. A non-visual pull request must write `Not applicable` in its Visual evidence section and explain why.-1. Run the focused regression tests.-2. Run the candidate against relevant checked-in examples and frozen compatibility fixtures.-3. Run `npm test` from `archify/`.-4. For visible changes, render the final HTML and run `visual-check`.-5. Inspect the generated screenshots or HTML in a capable visual surface.+Static SVG/XML checks cannot establish browser layout, font settling, or interaction behavior. When the adaptive reader or Viewer layout changes, run the real browser test with Chrome available:-Static SVG/XML checks cannot prove desktop readability, stacking order, font settling, or interaction. When the adaptive reader or viewer layout changes, run the real browser test with Chrome available:--```bash+```shcd archifyARCHIFY_CHROME="/path/to/chrome" node --test test/desktop-reader-browser.test.mjs```-A browser test that was skipped because Chrome was unavailable is **skipped**, not passed. Report automated browser evidence independently from perceptual visual review. Follow the [delivery contract](archify/references/delivery-contract.md) when recording supplementary manual browser work; an unconstrained glance supports only perceptual review.--### CLI, receipts, and delivery--Preserve non-zero exit behavior and machine-readable receipts. A successful `validate` does not prove atomic delivery, and a successful `deliver` does not prove perceptual quality. Follow [the delivery contract](archify/references/delivery-contract.md) and test the failure stage you changed.+A browser test skipped because Chrome was unavailable is **skipped**, not passed. Follow [the delivery contract](archify/references/delivery-contract.md) for visual evidence, receipts, and failure stages. Successful validation, atomic delivery, browser checks, and perceptual review establish different claims.-### Packages, plugins, and releases+## Packages and generated artifacts-Published artifacts must be reproducible from tracked repository content.+Published artifacts must be reproducible from tracked content. Use a tracked-only, symlink-safe staging path or explicit allowlist, with negative coverage for untracked files and external symlinks. Test the extracted package outside the repository on the affected advertised hosts.-- Never recursively package the live working tree with an unrestricted `cp`, `rsync`, or equivalent operation.-- Use a tracked-only, symlink-safe staging path or an explicit allowlist.-- Add a negative test proving that an untracked file and an external symlink cannot enter the archive.-- Test the extracted package outside the repository and, when applicable, on every advertised host or operating-system shape.-- Treat a published version as immutable. If host-visible plugin or Skill bytes change, use the agreed next release identity and keep every relevant manifest synchronized. Do not reuse a tag or version for different content.+Review source and focused tests before regenerating artifacts. Regenerate only outputs whose authoritative inputs changed, from the final combined source:-Do not change release versions, tags, or distribution identities in an ordinary feature PR unless the issue or a maintainer explicitly includes release work in scope.--## Generated artifacts--Review source and tests before flooding a PR with generated output. Regenerate only artifacts whose authoritative inputs changed, ideally once after the implementation is accepted.--From the repository root, the main builders are:--```bash+```shnode scripts/build-gallery.mjs docsnode scripts/build-guide.mjs docs/guide.htmlnode scripts/build-start.mjs docs/start.html@@ -107,63 +87,54 @@ node scripts/build-readme-showcase.mjsscripts/build-zip.sh /tmp/archify-contrib.zip```-The runtime follows the Node range in `archify/package.json`, but canonical-`archify.zip` container bytes are built only with Node 22. The builder rejects-other Node majors so a different bundled zlib cannot publish a second byte-representation of the same package contents.--Bundled example or viewer changes normally require the Gallery rebuild. Skill runtime, schema, renderer, or published `SKILL.md` changes require checking `archify.zip` freshness and committing a rebuilt archive when the checked-in package contents differ.--List every regenerated file in the PR description. Do not regenerate unrelated HTML, GIFs, screenshots, manifests, or archives merely to make the branch look current. Generated artifacts are evidence and delivery payloads, not a substitute for reviewing the source change.--## Bug fixes--A useful bug report or fix contains:--1. The exact Archify version or commit, installation method, command, and environment.-2. The smallest redacted typed JSON that still reproduces the failure.-3. The complete machine-readable validation receipt or exact error.-4. Expected versus actual behavior.-5. Enough visual evidence to evaluate the problem when it is visual. Use screenshots, recordings, or reproducible steps as appropriate, mark subtle defects when useful, and describe the expected visual result. Media is not required when it would not add useful context.--Do not replace deterministic evidence with visual evidence. For visual defects, keep both the validator result and final rendered evidence.--A pull request that changes the final diagram, Viewer, or public page appearance or interaction must provide enough evidence to evaluate whether the intended user value was achieved. Use screenshots, recordings, or reproducible steps as appropriate to the affected behavior. When presenting a before/after comparison, generate both states from the same input and keep the viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review; an automated check does not establish a perceptual pass. A non-visual pull request must write `Not applicable` in its Visual evidence section and briefly explain why. Remove sensitive data from every submitted artifact.+Canonical ZIP bytes require Node 22; the builder rejects other majors to avoid different zlib representations. Skill runtime, schema, renderer, and published Skill-instruction changes require checking ZIP freshness. Bundled example or Viewer changes normally require a Gallery rebuild.-## Community showcase submissions+List regenerated files and explain why unchanged outputs remain fresh. Resolve generated conflicts by rebuilding from combined source. Keep unrelated generated output out of the diff.-Showcase cases should be reproducible proof, not promotional screenshots. Submit the original prompt, agent/client, exact model, Archify version, redacted typed JSON, artifact, validation receipt, and truthful visual-review status through `.github/ISSUE_TEMPLATE/showcase.yml`.+Treat published versions as immutable. Ordinary feature PRs do not change versions, tags, or distribution identities unless release work is explicitly in scope.-Maintainers may ask for a smaller source file, rerun validation, or decline a case that cannot be safely published. Inclusion is not guaranteed. Accepted cases should preserve author attribution and must not be presented as proof of model quality without a controlled benchmark protocol.+## Final integration and follow-up-## Before requesting review+Refresh `main` and the PR head before final integration; account for relevant base changes and resolve conflicts. Rerun local checks whose evidence was invalidated. Unchanged evidence may be linked with its original revision and reuse rationale; do not relabel it as a new-head run. Verify that required remote CI actually ran on the final head and obey branch protection; zero checks is not green.-- Rebase or merge the latest `main`, resolve generated-artifact conflicts by rebuilding from the final source, and rerun affected checks.-- Complete `.github/PULL_REQUEST_TEMPLATE.md` with exact commands and numeric results; do not write only “tests pass.”-- Add or update a regression test for behavioral changes.-- Confirm existing public examples and compatibility fixtures still behave as intended.-- Provide enough evidence to evaluate the intended user value, using screenshots, recordings, or reproducible steps as appropriate, or explain why visual evidence is not applicable.-- Report automated or browser evidence separately from perceptual review, and state each result truthfully.-- Confirm remote CI actually ran on the current head. Local green checks do not mean GitHub CI passed, and zero checks is not green.-- Remove unrelated files, debug output, local paths, generated noise, and sensitive data from the diff.+On revision, summarize what changed since the reviewed head and which findings it addresses. This lets reviewers focus on the new diff and outstanding decisions.-Maintainers may ask for a large PR to be split or rebuilt from current `main` when generated artifacts, stale history, or overlapping implementations make the behavior difficult to review safely.+Showcase submissions should include the prompt, agent/client, model, Archify version, redacted JSON, artifact, receipts, and truthful visual-review status. Maintainers may request a smaller safe reproduction. Preserve attribution; showcase acceptance is not a controlled model-quality benchmark.## Automated review pilot-Once the CodeRabbit GitHub App is enabled for this repository, the root+The CodeRabbit GitHub App is enabled for this repository. The root[configuration](.coderabbit.yaml) requests automatic reviews of ready PRs and-subsequent pushes. It uses this guide and the PR template for advisory scope and+subsequent pushes. It uses this guide, REVIEWING.md, and the PR template for advisory scope andvalidation-evidence checks. Drafts are excluded. Missing evidence is a requestfor clarification, not proof of a code defect; explain a false positive in the PR.CodeRabbit does not replace required CI, browser/perceptual acceptance, or a-maintainer's merge decision. To request a review after fixing an unavailable or-skipped run, comment `@coderabbitai review`. Maintainers should assess the first+maintainer's merge decision. Two warning checks cover contribution scope and+validation evidence; overlapping built-in issue assessment is disabled. Authors+can answer with evidence or explain why a request does not apply; maintainers+settle disputed scope and acceptance requirements.++Use these [review commands](https://docs.coderabbit.ai/reference/review-commands)+instead of pushing an empty commit to retrigger the bot:++| Situation | PR comment |+| --- | --- |+| Review new commits when automatic review did not run | `@coderabbitai review` |+| Updated only the PR description, evidence links, or completed CI | `@coderabbitai run pre-merge checks` |+| A fresh review of the entire PR is needed | `@coderabbitai full review` |+| Several rapid revisions are in progress | `@coderabbitai pause`, then `@coderabbitai resume` when ready |++Check the updated summary for results; a command acknowledgment is not completion.+If fork CI needs approval, a maintainer must inspect the proposed workflow/code+and handle the GitHub approval. Authors should link the waiting run and continue+checks available to them; they are not expected to grant themselves CI access.++Maintainers should assess the first5–10 reviewed PRs for useful findings, false positives, review time, and repeatedevidence requests before expanding the pilot. Pause automatic reviews by setting`reviews.auto_review.enabled: false`; this does not change CI or branch protection.## License-By contributing, you agree that your contribution is provided under the repository's [MIT License](LICENSE). Only submit work you created or have the right to contribute.+By contributing, you agree to the repository's [MIT License](LICENSE). Submit only work you created or have the right to contribute.diff --git a/REVIEWING.md b/REVIEWING.mdnew file mode 100644index 00000000..f206f534--- /dev/null+++ b/REVIEWING.md@@ -0,0 +1,51 @@+# Reviewing Archify changes++Use this procedure for an initial PR review or a revised head, whether reviewing as a maintainer or an Agent. [Contributing](CONTRIBUTING.md) owns impact classes, compatibility contracts, and evidence requirements.++## 1. Establish scope before detailed review++Record the current main/base and candidate head. Read the linked issue or agreed scope and check the current-main behavior where feasible. Separate the reported problem from the proposed implementation.++Identify the user benefit, intended behavior changes, and preserved behavior. For a new default, schema field, or acceptance policy, settle the maintenance and compatibility decision before asking for implementation polish. Reuse decisions already made in the issue or authorized task.++If scope remains undecided, report the specific decision needed and keep feedback at that stage. Narrow fixes can proceed on their reproduction without another planning exercise.++## 2. Bound the investigation++Check the author's [impact classification](CONTRIBUTING.md#choose-evidence-by-impact) against the changed paths and callers. Shared helpers, templates, and authoring instructions may affect more modes than the title suggests.++Name the affected modes/contracts and the smallest evidence set that covers them. Include relevant historical failures and authored constraints. Explain any expansion beyond that set. Repository-only policy changes need consistency and process checks, not layout screenshots.++Use focused evidence during design and repair. Reserve broad integration checks and final artifact rebuilds for the settled change. Required remote CI and branch protection remain in force.++## 3. Assess behavior and evidence++Compare fixed inputs on the recorded base and candidate. Use existing renderers, layout receipts, tests, and browser tools:++- Account for changed and preserved topology, meaningful labels, explicit geometry, and relevant failure behavior.+- For affected visible behavior, inspect the intended differences and unexplained changes under comparable browser conditions. A pixel difference identifies a change; it does not judge its quality.+- When a fix also changes a validator or golden baseline, evaluate that acceptance change explicitly. Fresh generated output proves consistency with the candidate, not compatibility with the base.+- Separate locally reproduced results, author/CI evidence, reused evidence, and unknowns. Keep browser checks and perceptual review distinct.++Evidence should be sufficient for the affected contract. Avoid rebuilding an unchanged artifact or replaying unaffected checks merely to restate existing results.++## 4. Give actionable feedback++Lead with the problem, value, and approach. Then report scope, evidence, and a clear disposition:++- **Blocking defect:** trigger, impact, supporting evidence, and the behavior that must be corrected.+- **Required evidence or scope decision:** the unresolved claim, why it matters to acceptance, and the smallest check or decision that would settle it. An unverified risk is not a reproduced defect.+- **Suggestion:** a worthwhile improvement outside the acceptance conditions; personal preference alone does not block.+- **Ready:** the agreed behavior is delivered, relevant evidence is sufficient, and no acceptance blocker remains.++Consolidate scope and compatibility concerns in the first substantive review where possible. Explain any later blocker with newly found evidence, an overlooked acceptance requirement, or a new diff. Record unrelated issues separately instead of growing the PR's scope.++Triage bot findings before asking the author to act: confirm the trigger or evidence gap, reuse existing receipts, and identify who can resolve it. Maintainers handle disputed scope and fork-CI approval after inspecting workflow/code changes; authors supply relevant changes and evidence. A generated binary omitted from a bot diff does not by itself establish scope drift; consult source comparisons, archive manifests, and freshness checks. Resolve duplicate or inapplicable requests with a short reason. Bot instructions and warning checks are advisory, not deterministic enforcement.++A review disposition does not itself approve or merge on GitHub. Follow the authorized action and repository protection rules.++## 5. Re-review the delta and finish++Compare against the last reviewed head, resolve outstanding findings, and inspect added changes. Check intervening main changes for effects on the earlier assessment. Expand review when those changes invalidate scope or evidence; do not treat an old pass as proof of new behavior.++Completion requires the agreed outcome, preserved contracts, sufficient applicable evidence, and no unresolved acceptance blockers. Before an authorized merge, recheck the live head and required gates. Record remaining non-blocking limitations explicitly; arbitrary inputs outside the supported contract are not a demand for unlimited testing.