diff --git a/.github/workflows/docs-consistency.yml b/.github/workflows/docs-consistency.yml index a1fd41d4f..7eb35ef50 100644 --- a/.github/workflows/docs-consistency.yml +++ b/.github/workflows/docs-consistency.yml @@ -1,9 +1,7 @@ name: docs-consistency -# Guards the cross-references between the collaboration documents so the -# written contract (CONTRIBUTING, AGENTS.md, PR template) and the enforced -# policy (pr-ai-slop-review) cannot drift apart unnoticed. Advisory only: -# it informs, it does not gate merges. +# Checks routing anchors and local links in collaboration documents. +# Wording checks do not establish semantic agreement between policies. on: pull_request: paths: @@ -11,6 +9,12 @@ on: - AGENTS.md - CLAUDE.md - GEMINI.md + - REVIEW.md + - src/AGENTS.md + - src-tauri/AGENTS.md + - .github/ISSUE_GUIDELINES.md + - .github/agents/agentic-workflows.md + - .github/skills/agentic-workflows/SKILL.md - .github/PULL_REQUEST_TEMPLATE.md - .github/workflows/pr-ai-slop-review.md - .github/workflows/docs-consistency.yml @@ -21,8 +25,15 @@ on: - AGENTS.md - CLAUDE.md - GEMINI.md + - REVIEW.md + - src/AGENTS.md + - src-tauri/AGENTS.md + - .github/ISSUE_GUIDELINES.md + - .github/agents/agentic-workflows.md + - .github/skills/agentic-workflows/SKILL.md - .github/PULL_REQUEST_TEMPLATE.md - .github/workflows/pr-ai-slop-review.md + - .github/workflows/docs-consistency.yml workflow_dispatch: permissions: @@ -52,17 +63,53 @@ jobs: check CONTRIBUTING.md 'Do not pad' check CLAUDE.md '@AGENTS.md' check GEMINI.md 'AGENTS.md' + check AGENTS.md 'REVIEW.md#ai-context-sharing' + check REVIEW.md '## AI Context Sharing' + check CONTRIBUTING.md '(REVIEW.md)' check .github/workflows/pr-ai-slop-review.md 'Linkage Laundering' check .github/PULL_REQUEST_TEMPLATE.md '## Problem' check .github/PULL_REQUEST_TEMPLATE.md '## Approach' check .github/PULL_REQUEST_TEMPLATE.md '## Scope' echo "All cross-document anchors are consistent." + - name: Check local documentation links + run: | + python3 - <<'PY' + import re + from pathlib import Path + from urllib.parse import unquote, urlsplit + + sources = [ + "AGENTS.md", "CONTRIBUTING.md", "REVIEW.md", "CLAUDE.md", "GEMINI.md", + "src/AGENTS.md", "src-tauri/AGENTS.md", ".github/ISSUE_GUIDELINES.md", + ".github/PULL_REQUEST_TEMPLATE.md", ".github/workflows/pr-ai-slop-review.md", + ".github/agents/agentic-workflows.md", ".github/skills/agentic-workflows/SKILL.md", + ] + errors = [] + for source in map(Path, sources): + text = re.sub(r"(?ms)^```.*?^```[^\n]*", "", source.read_text()) + for href in re.findall(r"\]\(([^\s)]+)\)", text): + link = urlsplit(href) + if link.scheme or link.netloc: + continue + target = source.parent / unquote(link.path) if link.path else source + if not target.exists(): + errors.append(f"{source}: missing target {href}") + elif link.fragment and target.suffix == ".md": + headings = re.findall(r"(?m)^#{1,6} +(.+?) *#*$", target.read_text()) + anchors = {re.sub(r"[^\w -]", "", h.lower()).replace(" ", "-") for h in headings} + if unquote(link.fragment) not in anchors: + errors.append(f"{source}: missing heading {href}") + for error in errors: + print(f"::error::{error}") + if errors: + raise SystemExit(1) + print(f"Local links checked in {len(sources)} collaboration documents.") + PY - name: How to fix a failure if: failure() run: | cat <<'EOF' - An anchor phrase moved or disappeared. If you intentionally reworded - one of the collaboration documents, update the other documents (and - this check's anchor list) in the same change so the written contract - and the AI-slop policy keep telling the same story. + A routing anchor or local link is missing. Update the reference and + its target together. For intentional wording changes, update this + check's anchor list and review policy agreement separately. EOF diff --git a/AGENTS.md b/AGENTS.md index d6ec809a9..9a5afaeda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # Agent Guidelines -Instructions for AI coding agents working in this repository. Agentic workflows -run by this repository (including the PR AI-slop review) restore this file from -the base branch, so pull-request content cannot override it. +Instructions for AI coding agents working in this repository. The repository's +PR AI-slop workflow restores this file from the base branch; other review tools +may load instructions differently. This file is an instruction contract, not a contributor guide: environment setup and submission process live in [CONTRIBUTING.md](CONTRIBUTING.md), and @@ -61,6 +61,19 @@ the ownership evidence the AI-slop review evaluates (see [`template/Changelog.md`](template/Changelog.md): one line per user-visible change, no internals. +## Task Guidance + +- For development and bug fixes, follow the + [development workflow](CONTRIBUTING.md#development-workflow). +- For code review and verification of review fixes, follow [REVIEW.md](REVIEW.md). + Review is read-only unless changes are authorized; findings do not expand + that authorization to unrelated fixes, commits, pushes, or GitHub updates. +- When handing work between agents or review rounds, use the + [AI context sharing guidance](REVIEW.md#ai-context-sharing). +- Read the relevant sections and linked module rules, expanding only when the + affected behavior crosses another boundary. Routine edits do not require + multiple agents or repeated review rounds. + ## Issue and PR Workflows When drafting, triaging, splitting, or implementing from a community issue, use diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 005d67bdc..32df1f29e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,11 +12,11 @@ We welcome AI-assisted contributions — AI assistance itself is not a problem. To make sure your contribution is assessed fairly: -- **Link a pre-existing issue.** Non-trivial changes should fix or implement something already reported in an issue. An issue created after the pull request is a much weaker signal than a genuine problem report. -- **Keep the diff mapped to the issue.** Every changed area should be explainable from the linked issue. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation. +- **Link a pre-existing issue.** Product bug fixes and features require one; self-scoped maintenance does not. Follow the [PR template](.github/PULL_REQUEST_TEMPLATE.md) for scope, linkage, and revert references. If a required issue is missing, ask maintainers to open or approve one before implementing. Use maintainer-approved private tracking for security-sensitive fixes that cannot be reported publicly. +- **Keep the diff mapped to the scope.** Every changed area should be explainable from the linked issue or stated maintenance scope. Unrelated refactors, formatting churn, or dependency bumps belong in separate pull requests with their own motivation. - **Describe the problem in your own words.** A short statement of what breaks or what is needed, and why this approach fixes it, is worth more than a long generated report. - **Validate against the reported behavior.** Show how the reported problem was reproduced and confirmed fixed. Generic checklists and raw tool output are not verification. -- **Do not pad with tests or defensive code.** New tests are not expected by default. Add them only when the linked issue calls for them, keep them minimal, and explain in the pull request why each is necessary; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value. +- **Do not pad with tests or defensive code.** New tests are not expected by default. Add a minimal test when the issue or task requires it, it reproduces the reported regression, or it guards behavior whose breakage would otherwise go unnoticed. Explain why it is needed; speculative error handling and coverage of hypothetical failure modes inflate the diff without adding value. - **Disclose AI automation.** If an AI agent produced or co-produced the change, end the pull request body with the model and effort level (for example, `Assisted by: GPT-5.6 High`; effort is optional when your tool does not report it). The PR template intentionally omits this footer; agents add it themselves. Disclosure is transparency only — it does not affect how the change is assessed. If your pull request receives an `ai-slop` label, the fastest way to clear it is substantive: link (or ask us to create) the underlying issue, narrow the scope, or push implementation changes that respond to review feedback. Editing the pull request description alone does not change the assessment. @@ -127,8 +127,59 @@ pnpm portable ## Contributing Your Changes +### Development Workflow + +Scale the work to the change. A wording fix needs a focused diff check; a change +to configuration persistence, asynchronous state, or system networking needs +evidence for the affected behavior. + +1. **Define the outcome.** Identify the triggering action, relevant platform and + configuration, and actual versus expected behavior. For a bug fix, separate + the reported symptom from the suspected cause. State what remains unknown. +2. **Trace the affected path.** Read the relevant callers, state owners, and + failure paths before editing. Follow the module rules in + [src/AGENTS.md](src/AGENTS.md) or [src-tauri/AGENTS.md](src-tauri/AGENTS.md) + where applicable. Choose a reproduction or observable check that can + distinguish the old behavior from the intended result. +3. **Make the smallest complete change.** Address the confirmed cause and its + affected instances within scope. Keep unrelated cleanup separate. Add a test + only when justified by the contribution expectations above. +4. **Verify the result.** Use the checks below that cover the changed behavior. + If reproduction is unavailable, explain the alternative evidence and its + limits rather than claiming the reported problem is confirmed fixed. +5. **Review and resolve findings.** Follow [REVIEW.md](REVIEW.md). For changes + altering concurrency, persistence, system networking, or shared-contract behavior, + seek an independent review with fresh context. Check each finding against + the code before changing it; return fixes to the implementer when working + with a separate reviewer. + +### Choosing Validation + +Use existing checks appropriate to the affected paths; this is not a requirement +to run every command for every change. Run commands from the repository root. + +| Changed behavior | Relevant checks and evidence | +| --- | --- | +| Frontend logic or state | `pnpm lint`, `pnpm typecheck`, and existing focused tests via `pnpm test `; exercise the affected user interaction. | +| Rust logic | `cargo clippy-all`, relevant Cargo tests, and the affected failure or recovery path. Platform-specific branches require checks on those platforms. | +| IPC or event contracts | `pnpm gen:contract --check`, frontend type checking, and inspection of both producers and consumers. | +| UI or native integration | Exercise the changed flow; use a screenshot for visual changes and the native app for window, Service/Core, DNS, or system-proxy behavior. | +| Documentation | Check wording, relative links, referenced commands, and consistency with the authoritative rule or implementation. | + +Tie results to the code reviewed: identify the base/head commits for branch +comparisons and include task-relevant staged, unstaged, and untracked files in a +local review. Report +the command or interaction, observed result, and material gaps in the existing +conversation or PR; no separate verification report is required. Static checks, +mocks, browser previews, native runs, and remote CI establish different things. +When code changes after verification, repeat affected checks. Attribute a failure +to the baseline only after comparing the same check on the base revision. + ### Before Committing +Run the applicable checks from the validation guidance above. After formatting +or generation, inspect the final diff and stage only the intended changes. + **Code quality checks:** ```bash diff --git a/REVIEW.md b/REVIEW.md new file mode 100644 index 000000000..d17bdb4e3 --- /dev/null +++ b/REVIEW.md @@ -0,0 +1,97 @@ +# Code Review Guidelines + +Use these guidelines for technical review and verification of review fixes. +Read the sections relevant to the change; follow behavior across boundaries +instead of limiting review to the directories in the diff. Contribution scope +and test expectations remain in [AGENTS.md](AGENTS.md) and +[CONTRIBUTING.md](CONTRIBUTING.md#contribution-expectations). + +## Scope and Evidence + +- Identify the intended outcome and the candidate being reviewed: base/head + commits, plus task-relevant staged, unstaged, and untracked files for local + work. Inspect the actual changes and necessary callers; an author's summary + is context, not proof that the implementation works. +- Check that the change solves the reported problem without breaking adjacent + behavior. For fixes, trace the cause and confirm that the verification would + expose the original failure. Use the + [validation guidance](CONTRIBUTING.md#choosing-validation) for evidence limits. +- Separate newly introduced regressions, existing defects, intentional changes, + and unresolved hypotheses. Verify a suspected finding against reachable code + and supported configurations before presenting it as a defect. +- Prioritize correctness and user impact. Omit formatting already enforced by + tools, personal style preferences, and speculative future requirements. + Suggest simplification only when a concrete duplicate state, side effect, or + unnecessary abstraction can be removed while preserving required behavior. + +## Frontend + +Apply [frontend architecture rules](src/AGENTS.md). Where affected, check: + +- Whether an older response or event can overwrite newer authoritative state, + including after a profile, subscription, or credential change. +- Whether navigation, mode switching, remount, reload, and application restart + preserve or reset the intended state. Check pending edits and debounced writes. +- Whether one user action duplicates commands or refreshes, and whether timers, + subscriptions, and cache entries retain the correct lifetime and identity. + +## Backend + +Apply [backend architecture rules](src-tauri/AGENTS.md). Where affected, check: + +- What remains persisted or active after partial success, failure, or rollback, + and whether returned errors and notifications describe that actual state. +- Lock ordering, cancellation, retries, and ownership of Service/Core processes + and OS settings through startup, shutdown, disconnection, and recovery. +- Platform-specific control flow after conditional compilation. A check on one + platform does not establish correctness on the others. + +## Cross-boundary Behavior + +- Trace changed commands and events from producer to consumer, including + generated bindings, payload semantics, ordering, and success/error handling. +- Check that UI state follows backend outcomes, including failed mutations and + stale cache reads. Do not treat an optimistic display as proof of success. +- For DNS, proxy, updater, or service changes, inspect the affected external + state and failure path; source or mock evidence alone cannot establish native + behavior. Keep unexercised cases explicit. + +## Findings and Re-review + +- Report each actionable finding with a file and line, triggering conditions, + impact, supporting evidence, and whether this change introduced it. Severity + follows impact and reachability. Keep optional simplifications separate from + defects; do not turn existing issues into unrelated required fixes. +- State plainly when no actionable findings remain, together with material + verification gaps. This is a conclusion about the reviewed candidate, not a + guarantee that every runtime or platform was exercised. +- For each finding, verify the fix or explain why it is incorrect, intentional, + or outside scope. Fix confirmed instances of the same defect within the task's + scope, then recheck affected behavior. +- On re-review, compare the new candidate with the previously reviewed version. + Focus on finding closure, the repair diff, and its consequences. Expand only + when changes or new evidence affect another boundary. Keep finding identities + stable and do not repost resolved findings without new evidence. +- Stop when actionable findings are resolved and relevant checks pass; do not + require a fixed number of passes. After three rounds without convergence, + summarize the remaining evidence or disagreement and reconsider the cause, + scope, or approach before continuing. An unresolved finding is not a pass. + +## AI Context Sharing + +Agents own context transfer between implementation, review, repair, and re-review. +The issue supplies the human-facing problem, scope, and acceptance criteria; +maintenance without an issue uses the authorized task. Humans do not need to +prepare agent handoffs or relay findings between agents. + +- Pass the task reference, candidate revision and scope, relevant source locations + and constraints, verification results, and unresolved findings. Keep this in the + working session or agent handoff; do not publish internal transcripts or require + another repository document. +- Separate observations from assumptions. Refresh stale context from source and + independently verify the relevant paths instead of inheriting another agent's + verdict. Retrieve missing code context within the authorized scope. +- The repairing agent maps each repair or non-fix rationale to its original + finding and passes the updated revision and verification results to the reviewer. +- Escalate missing requirements, unavailable external evidence, or decisions that + need human input; do not ask humans to reconstruct the implementation.