From 3ca8bd8bd58b7ad2519deb19e3fdf0130b7a3472 Mon Sep 17 00:00:00 2001 From: Xelvanas Date: Sat, 23 May 2026 01:27:54 +1000 Subject: [PATCH 1/4] Add contributor workflow docs --- .github/pull_request_template.md | 76 +++++++++++++ CONTRIBUTING.md | 189 +++++++++++++++++++++++++++++++ README.md | 4 + scripts/check-docs.mjs | 34 ++++++ 4 files changed, 303 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..195fbe1 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,76 @@ + + + +## Linked Issue + + + + + +Closes # + +## Why This Change + + + +- + +## Owner And Impact + + + +- Owner: +- Behavior changed: +- Expected impact area: +- Dependent callers reviewed: +- Affected modes/capabilities: +- Rust/TypeScript boundary touched: + +## What Changed + + + +- + +## Architecture And AI-Assisted Review + + + +- [ ] Followed nearby repo patterns instead of adding broad helpers, barrels, routers, or compatibility shims +- [ ] Confirmed the change lives in the owning layer/module +- [ ] Avoided accidental leakage between chat, roleplay, and game paths +- [ ] Removed obsolete fallback, placeholder, or fake-success code made unnecessary by the change +- [ ] Checked relevant edge cases and failure paths +- [ ] No generated-by lines, AI co-author trailers, or private local paths were added + +## Validation + + + + +- [ ] `pnpm typecheck` passes locally +- [ ] `pnpm check:rust` passes locally +- [ ] `pnpm check:docs` passes locally +- [ ] `pnpm build` passes locally, if imports, bundling, or runtime UI paths changed +- [ ] `pnpm check` passes locally, if this PR is ready for broad evaluation +- [ ] Ran the app and clicked through the changed workflow manually +- [ ] Checked relevant edge cases, such as light/dark mode, mobile viewport, empty states, error paths, provider/storage failures, or persisted-data migration paths +- [ ] Read and followed `CONTRIBUTING.md`, `AGENTS.md`, and the relevant `docs/developer/` pages + +### Manual Verification Notes + + + + +- + +## Docs And Release Impact + +- [ ] No docs/release changes needed +- [ ] Updated developer or user docs as needed +- [ ] Updated release notes/changelog if this is user-facing and release-noteworthy +- [ ] Version/release files updated only if this PR intentionally includes a version bump + +## UI Evidence + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c21c824 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,189 @@ +# Contributing to Marinara Engine Refactor + +This is the canonical contributor guide for ME-Refactor. Use it with `README.md` for the product overview, `docs/developer/` for architecture and run/build guidance, and `AGENTS.md` for repository agent workflow rules. + +## Tech Stack + +| Layer | Technology | +| --- | --- | +| Desktop shell | Tauri v2, Rust stable toolchain | +| Frontend | React 19, Tailwind CSS v4, Framer Motion, Zustand, React Query | +| Product engine | TypeScript 5, Zod, React-free engine modules | +| Local capabilities | Rust command and capability crates for storage, assets, provider transport, and integrations | +| Build | Vite 7, Tauri CLI, Cargo, pnpm 10 | + +## Development Setup + +Prerequisites: + +- Node.js and pnpm through the repo-pinned `packageManager` +- Rust stable toolchain +- Platform-specific Tauri prerequisites for your operating system +- Git + +Typical local setup: + +```bash +git clone https://github.com/Pasta-Devs/Marinara-Engine-Refactor.git +cd Marinara-Engine-Refactor +git fetch origin +git switch main +pnpm install +pnpm tauri dev +``` + +Useful entry points: + +- `pnpm tauri dev` starts the normal desktop development app. Tauri starts Vite on `http://localhost:1420` and opens the native window. +- `pnpm dev` starts only the Vite web shell. This is useful for React layout checks, but it does not prove Tauri-only filesystem, command, asset protocol, dialog, provider, or native-window behavior. +- `pnpm docs:dev` serves the developer docs at `http://127.0.0.1:4174/`. +- `pnpm build` typechecks and builds the frontend into `dist/`. +- `pnpm tauri build` builds the desktop bundle. Tauri runs `pnpm build` first through `src-tauri/tauri.conf.json`. + +For more detail, read `docs/developer/run-build.html`. + +## Branches + +ME-Refactor uses `main` as the default integration branch. + +Guidelines: + +- Base new feature, bugfix, and documentation branches on `origin/main`. +- Use focused branch names such as `fix/provider-timeout-message` or `feature/game-asset-browser`. +- Open draft PRs against `main` while implementation is still in progress. +- Do not commit, merge, or push directly to `main` unless a maintainer explicitly asks for that exact operation. +- Do not force-push, delete branches, hard reset, or overwrite someone else's work without explicit maintainer approval. + +## Repo Layout + +- `src/app/` - React bootstrap, shell, providers, and startup wiring. +- `src/features/` - feature-owned React UI, hooks, UI stores, and feature workflows. +- `src/shared/` - shared frontend UI primitives, browser helpers, stores, and generic utilities. +- `src/shared/api/` - typed Tauri adapter functions and channel/listen wrappers. +- `src/engine/` - React-free TypeScript product engine, contracts, generation, agents, repositories, and mode behavior. +- `src-tauri/` - Tauri host code, Rust commands, capability crates, native storage, assets, provider transport, and integrations. +- `docs/developer/` - developer docs for architecture, modules, impact areas, and local run/build commands. +- `skills/` - repo-local agent guidance for architecture, mode separation, bugfix discipline, and onboarding. +- `updates/` - local project status, bug ownership, and work tracking. + +## Architecture And Ownership + +Dependency direction is the main guardrail: + +```text +React app/features + -> shared/api Tauri adapters + -> TypeScript engine use cases + -> engine capability ports + -> Rust Tauri commands + -> Rust capability crates +``` + +Before changing behavior, read these docs: + +- `docs/developer/architecture.html` +- `docs/developer/modules.html` +- `docs/developer/impact-areas.html` + +Use this impact brief before fixes, features, and refactors: + +```text +Owner: +Behavior changed: +Expected impact area: +Dependent callers: +Affected modes: +Rust/TS boundary touched: +Checks planned: +``` + +Core ownership rules: + +- Product behavior belongs in the TypeScript engine or the owning feature, not in generic UI glue. +- Privileged local work belongs behind Tauri commands and Rust capabilities. +- React components should not duplicate prompt rules, mode orchestration, storage formats, or provider transport behavior. +- Engine code must not import React, Zustand stores, `@tauri-apps/api`, or concrete `src/shared/api` adapters. +- Chat, roleplay, and game are separate product paths. Do not route one mode through another or hide mode differences behind a generic mode flag. +- Shared code should be truly shared and lower-level. Avoid broad `utils` files, convenience barrels, generic routers, fake local API bridges, and one-line compatibility shims. + +## AI-Assisted Contribution Rules + +AI-assisted code is welcome when it is reviewed, simplified, and owned by the contributor. + +Before accepting generated or AI-assisted code: + +- Match nearby repo patterns and naming. +- Confirm the change lives in the owning layer or module. +- Remove unused abstraction, unused dependencies, placeholder code, fake-success branches, and obsolete fallbacks. +- Check failure paths, empty states, persisted-data edge cases, and relevant mode boundaries. +- Explain the user problem and impact area in the PR, not just the file changes. +- Do not add generated-by lines, AI self-attribution, AI co-author trailers, or private local paths. + +If an AI agent ticks PR checklist boxes, treat those boxes as a to-do list, not proof. Verify each item yourself and untick anything you have not personally confirmed. + +## Validation + +Run the checks that match the changed area: + +```bash +pnpm typecheck +pnpm check:rust +pnpm check:docs +pnpm build +pnpm check +``` + +Use them this way: + +- `pnpm typecheck` for TypeScript, React, shared API, or engine changes. +- `pnpm check:rust` for Rust commands, Tauri capabilities, provider transport, storage, assets, or integrations. +- `pnpm check:docs` for docs, repo guidance, or repo-local skill changes. +- `pnpm build` when imports, bundling, production frontend behavior, or app startup changed. +- `pnpm check` for PR readiness, release/runtime risk, broad shared-contract changes, or when narrower checks cannot cover the risk. + +There is not currently a meaningful automated test suite beyond these checks. Do not present `pnpm test` as a reliable gate in docs or PR descriptions unless the repo adds and documents that script. + +Manual verification matters. For UI and workflow changes, run the app and click through the changed path. Browser-only checks can help with layout and React behavior, but native Tauri behavior still needs the desktop app. + +## Before You Open A Pull Request + +1. Open or link an issue when the change needs maintainer alignment, product discussion, or bug tracking. +2. Keep the scope tight. Separate unrelated refactors from user-facing fixes, feature work, and docs changes. +3. Identify the owner, impact area, dependent callers, affected modes or capabilities, and checks planned. +4. Test the change yourself. Include exact validation commands and manual verification notes. +5. Add screenshots or recordings for UI changes. +6. Update docs in the same PR when behavior changes make existing docs misleading. + +## Pull Request Expectations + +- Target `main`. +- Open the PR as a draft while work is still in progress. +- Link the issue or feature request when one exists. +- Explain why the change matters to users or maintainers. +- Fill out the owner and impact section in the PR template. +- Keep PRs focused and reviewable. +- Leave validation and manual verification checkboxes unchecked unless you personally completed them. +- Call out remaining risk or native/manual QA still needed. + +## Documentation Rules + +- `README.md` is the user-facing product overview and quickstart. +- `CONTRIBUTING.md` is the canonical contributor workflow document. +- `AGENTS.md` is the repo-local agent instruction source. +- `docs/developer/` is the developer documentation source for architecture, modules, impact areas, and run/build instructions. +- `skills/` contains repo-local agent guidance and should change only when durable workflow or architecture guidance changes. +- `updates/` tracks bug reports, active ownership, and current work status. + +If a change makes an existing doc misleading, update that doc in the same PR. + +## Versioning And Releases + +Current policy: + +- Canonical application version source: root `package.json`. +- Tauri bundle version lives in `src-tauri/tauri.conf.json` and should stay synchronized with the app version when releases are prepared. +- Release tags should use `vX.Y.Z` when the repo begins publishing tagged releases. +- Do not bump versions unless the PR intentionally prepares a release or a maintainer asks for a version bump. +- Do not commit built installer binaries or generated release artifacts. + +ME-Refactor's release workflow is still lighter than the legacy Marinara Engine workflow. Do not copy legacy workspace, Android, Windows installer, Docker, or old release-branch steps into this repo unless those systems are reintroduced here. diff --git a/README.md b/README.md index 5b8f0ba..bc2e70f 100644 --- a/README.md +++ b/README.md @@ -13,3 +13,7 @@ pnpm docs:dev Then open `http://127.0.0.1:4174/`. The docs cover getting started, local run/build commands, architecture, module ownership, and impact areas for bug fixes and new features. + +## Contributing + +Read `CONTRIBUTING.md` before opening a pull request. It covers branch flow, architecture ownership, AI-assisted review expectations, and validation. diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index 35459fb..bdd83cc 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -3,7 +3,9 @@ import { dirname, resolve } from "node:path"; const requiredDocs = [ "AGENTS.md", + "CONTRIBUTING.md", "README.md", + ".github/pull_request_template.md", "package.json", "docs/developer/index.html", "docs/developer/getting-started.html", @@ -90,4 +92,36 @@ if (packageJson.scripts?.docs) { throw new Error("Do not add a docs script; pnpm docs collides with package documentation behavior."); } +const contributing = await readFile("CONTRIBUTING.md", "utf8"); +for (const expected of [ + "pnpm tauri dev", + "docs/developer/architecture.html", + "docs/developer/modules.html", + "docs/developer/impact-areas.html", + "AI-Assisted Contribution Rules", +]) { + if (!contributing.includes(expected)) { + throw new Error(`CONTRIBUTING.md is missing expected guidance: ${expected}.`); + } +} + +for (const staleLegacyTerm of [ + "staging", + "packages/client", + "packages/server", + "Fastify", + "Docker / Podman", +]) { + if (contributing.includes(staleLegacyTerm)) { + throw new Error(`CONTRIBUTING.md contains legacy repo guidance: ${staleLegacyTerm}.`); + } +} + +const pullRequestTemplate = await readFile(".github/pull_request_template.md", "utf8"); +for (const expected of ["Owner And Impact", "Architecture And AI-Assisted Review", "CONTRIBUTING.md"]) { + if (!pullRequestTemplate.includes(expected)) { + throw new Error(`Pull request template is missing expected guidance: ${expected}.`); + } +} + console.log(`Checked ${requiredDocs.length} docs and repo guidance files.`); From ab1ea3fc4aac0c60ecffd8964af57c64d469c44b Mon Sep 17 00:00:00 2001 From: Xelvanas Date: Sat, 23 May 2026 01:52:33 +1000 Subject: [PATCH 2/4] Reinforce failure path review guidance --- .github/pull_request_template.md | 14 ++++++++++++++ CONTRIBUTING.md | 18 ++++++++++++++++++ scripts/check-docs.mjs | 10 +++++++++- 3 files changed, 41 insertions(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 195fbe1..bd36079 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -43,6 +43,20 @@ Closes # - [ ] Checked relevant edge cases and failure paths - [ ] No generated-by lines, AI co-author trailers, or private local paths were added +## Failure Path Checks + + + +- [ ] Missing, empty, stale, or malformed persisted records considered +- [ ] Missing, moved, invalid, oversized, or permission-blocked files/assets considered +- [ ] Provider, network, timeout, cancellation, or empty-response behavior considered +- [ ] Tauri command, dialog, filesystem, asset protocol, or native-window-only behavior considered +- [ ] Import/export, duplicate ID, old-shape data, or invalid JSON behavior considered +- [ ] Loading, empty, disabled, and error UI states considered +- [ ] Light/dark mode, small viewport, long text, and content overflow considered +- [ ] Chat/roleplay/game mode boundary risk considered when shared code changed +- [ ] Remaining unverified failure paths are called out below + ## Validation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c21c824..2b73b1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,6 +121,24 @@ Before accepting generated or AI-assisted code: If an AI agent ticks PR checklist boxes, treat those boxes as a to-do list, not proof. Verify each item yourself and untick anything you have not personally confirmed. +## Failure Path Checks + +Happy-path behavior is not enough for a PR to be reviewable. Before opening or updating a PR, identify the failure paths that apply to the changed owner and write down which ones were tested, inspected, or left for follow-up. + +Common ME-Refactor failure paths: + +- Missing, empty, stale, or malformed persisted records. +- Missing, moved, invalid, oversized, or permission-blocked local files and assets. +- Provider failures, invalid credentials, offline network behavior, timeouts, aborted streams, and empty model responses. +- Tauri command failures, rejected dialogs, denied filesystem access, asset protocol issues, and native-window-only behavior. +- Import/export records from older app shapes, partial imports, duplicate IDs, and invalid JSON. +- Cancelled, retried, regenerated, or interrupted generation flows. +- Loading, empty, disabled, and error UI states. +- Light/dark mode, small viewport, long text, and content overflow for UI changes. +- Mode boundary risk between chat, roleplay, and game when shared helpers, generation, prompts, storage, assets, or visual primitives change. + +You do not need to exhaustively test unrelated paths. Do state what you checked, what you only reviewed by code, and what still needs human or native-app QA. + ## Validation Run the checks that match the changed area: diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index bdd83cc..4697b3d 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -99,6 +99,8 @@ for (const expected of [ "docs/developer/modules.html", "docs/developer/impact-areas.html", "AI-Assisted Contribution Rules", + "Failure Path Checks", + "Missing, empty, stale, or malformed persisted records", ]) { if (!contributing.includes(expected)) { throw new Error(`CONTRIBUTING.md is missing expected guidance: ${expected}.`); @@ -118,7 +120,13 @@ for (const staleLegacyTerm of [ } const pullRequestTemplate = await readFile(".github/pull_request_template.md", "utf8"); -for (const expected of ["Owner And Impact", "Architecture And AI-Assisted Review", "CONTRIBUTING.md"]) { +for (const expected of [ + "Owner And Impact", + "Architecture And AI-Assisted Review", + "Failure Path Checks", + "Remaining unverified failure paths", + "CONTRIBUTING.md", +]) { if (!pullRequestTemplate.includes(expected)) { throw new Error(`Pull request template is missing expected guidance: ${expected}.`); } From 69300615dc79948327faf2003fbce3e20f8ebef5 Mon Sep 17 00:00:00 2001 From: Xelvanas Date: Sat, 23 May 2026 01:55:22 +1000 Subject: [PATCH 3/4] Revert "Reinforce failure path review guidance" This reverts commit ab1ea3fc4aac0c60ecffd8964af57c64d469c44b. --- .github/pull_request_template.md | 14 -------------- CONTRIBUTING.md | 18 ------------------ scripts/check-docs.mjs | 10 +--------- 3 files changed, 1 insertion(+), 41 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index bd36079..195fbe1 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -43,20 +43,6 @@ Closes # - [ ] Checked relevant edge cases and failure paths - [ ] No generated-by lines, AI co-author trailers, or private local paths were added -## Failure Path Checks - - - -- [ ] Missing, empty, stale, or malformed persisted records considered -- [ ] Missing, moved, invalid, oversized, or permission-blocked files/assets considered -- [ ] Provider, network, timeout, cancellation, or empty-response behavior considered -- [ ] Tauri command, dialog, filesystem, asset protocol, or native-window-only behavior considered -- [ ] Import/export, duplicate ID, old-shape data, or invalid JSON behavior considered -- [ ] Loading, empty, disabled, and error UI states considered -- [ ] Light/dark mode, small viewport, long text, and content overflow considered -- [ ] Chat/roleplay/game mode boundary risk considered when shared code changed -- [ ] Remaining unverified failure paths are called out below - ## Validation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b73b1c..c21c824 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -121,24 +121,6 @@ Before accepting generated or AI-assisted code: If an AI agent ticks PR checklist boxes, treat those boxes as a to-do list, not proof. Verify each item yourself and untick anything you have not personally confirmed. -## Failure Path Checks - -Happy-path behavior is not enough for a PR to be reviewable. Before opening or updating a PR, identify the failure paths that apply to the changed owner and write down which ones were tested, inspected, or left for follow-up. - -Common ME-Refactor failure paths: - -- Missing, empty, stale, or malformed persisted records. -- Missing, moved, invalid, oversized, or permission-blocked local files and assets. -- Provider failures, invalid credentials, offline network behavior, timeouts, aborted streams, and empty model responses. -- Tauri command failures, rejected dialogs, denied filesystem access, asset protocol issues, and native-window-only behavior. -- Import/export records from older app shapes, partial imports, duplicate IDs, and invalid JSON. -- Cancelled, retried, regenerated, or interrupted generation flows. -- Loading, empty, disabled, and error UI states. -- Light/dark mode, small viewport, long text, and content overflow for UI changes. -- Mode boundary risk between chat, roleplay, and game when shared helpers, generation, prompts, storage, assets, or visual primitives change. - -You do not need to exhaustively test unrelated paths. Do state what you checked, what you only reviewed by code, and what still needs human or native-app QA. - ## Validation Run the checks that match the changed area: diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index 4697b3d..bdd83cc 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -99,8 +99,6 @@ for (const expected of [ "docs/developer/modules.html", "docs/developer/impact-areas.html", "AI-Assisted Contribution Rules", - "Failure Path Checks", - "Missing, empty, stale, or malformed persisted records", ]) { if (!contributing.includes(expected)) { throw new Error(`CONTRIBUTING.md is missing expected guidance: ${expected}.`); @@ -120,13 +118,7 @@ for (const staleLegacyTerm of [ } const pullRequestTemplate = await readFile(".github/pull_request_template.md", "utf8"); -for (const expected of [ - "Owner And Impact", - "Architecture And AI-Assisted Review", - "Failure Path Checks", - "Remaining unverified failure paths", - "CONTRIBUTING.md", -]) { +for (const expected of ["Owner And Impact", "Architecture And AI-Assisted Review", "CONTRIBUTING.md"]) { if (!pullRequestTemplate.includes(expected)) { throw new Error(`Pull request template is missing expected guidance: ${expected}.`); } From 04fb5238f7b4018e025edc7efd1ce6c12c1aeb2e Mon Sep 17 00:00:00 2001 From: Xelvanas Date: Sun, 24 May 2026 22:09:18 +1000 Subject: [PATCH 4/4] Refine contributor PR guidance --- .github/pull_request_template.md | 16 ++++++---------- CONTRIBUTING.md | 7 +++++-- README.md | 2 +- scripts/check-docs.mjs | 3 ++- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 195fbe1..cb3041f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,6 @@ + ## Linked Issue @@ -32,22 +33,17 @@ Closes # - -## Architecture And AI-Assisted Review +## Architecture Notes - + -- [ ] Followed nearby repo patterns instead of adding broad helpers, barrels, routers, or compatibility shims -- [ ] Confirmed the change lives in the owning layer/module -- [ ] Avoided accidental leakage between chat, roleplay, and game paths -- [ ] Removed obsolete fallback, placeholder, or fake-success code made unnecessary by the change -- [ ] Checked relevant edge cases and failure paths -- [ ] No generated-by lines, AI co-author trailers, or private local paths were added +- ## Validation - - + +- [ ] `pnpm check:architecture` passes locally, if imports, file layout, feature boundaries, engine layers, shared APIs, or Rust command structure changed - [ ] `pnpm typecheck` passes locally - [ ] `pnpm check:rust` passes locally - [ ] `pnpm check:docs` passes locally diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c21c824..ef581af 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,7 +119,7 @@ Before accepting generated or AI-assisted code: - Explain the user problem and impact area in the PR, not just the file changes. - Do not add generated-by lines, AI self-attribution, AI co-author trailers, or private local paths. -If an AI agent ticks PR checklist boxes, treat those boxes as a to-do list, not proof. Verify each item yourself and untick anything you have not personally confirmed. +Human reviewers should verify checked PR checklist items before relying on them. Agents must not newly tick PR checklist boxes or untick boxes that were already checked; they should describe validation results and gaps in text instead. ## Validation @@ -127,6 +127,7 @@ Run the checks that match the changed area: ```bash pnpm typecheck +pnpm check:architecture pnpm check:rust pnpm check:docs pnpm build @@ -136,6 +137,7 @@ pnpm check Use them this way: - `pnpm typecheck` for TypeScript, React, shared API, or engine changes. +- `pnpm check:architecture` for import boundaries, layered ownership, shared modules, Rust command structure, or architecture-sensitive refactors. - `pnpm check:rust` for Rust commands, Tauri capabilities, provider transport, storage, assets, or integrations. - `pnpm check:docs` for docs, repo guidance, or repo-local skill changes. - `pnpm build` when imports, bundling, production frontend behavior, or app startup changed. @@ -162,7 +164,8 @@ Manual verification matters. For UI and workflow changes, run the app and click - Explain why the change matters to users or maintainers. - Fill out the owner and impact section in the PR template. - Keep PRs focused and reviewable. -- Leave validation and manual verification checkboxes unchecked unless you personally completed them. +- Human contributors may check validation and manual verification boxes only for items they personally completed. +- Agents should leave PR checklist boxes in their existing state and summarize proof or remaining gaps in text. - Call out remaining risk or native/manual QA still needed. ## Documentation Rules diff --git a/README.md b/README.md index bc2e70f..ab5ca1f 100644 --- a/README.md +++ b/README.md @@ -16,4 +16,4 @@ The docs cover getting started, local run/build commands, architecture, module o ## Contributing -Read `CONTRIBUTING.md` before opening a pull request. It covers branch flow, architecture ownership, AI-assisted review expectations, and validation. +Read `CONTRIBUTING.md` before opening a pull request. It covers branch flow, architecture ownership, AI-assisted contribution rules, and validation. diff --git a/scripts/check-docs.mjs b/scripts/check-docs.mjs index bdd83cc..1e90919 100644 --- a/scripts/check-docs.mjs +++ b/scripts/check-docs.mjs @@ -95,6 +95,7 @@ if (packageJson.scripts?.docs) { const contributing = await readFile("CONTRIBUTING.md", "utf8"); for (const expected of [ "pnpm tauri dev", + "pnpm check:architecture", "docs/developer/architecture.html", "docs/developer/modules.html", "docs/developer/impact-areas.html", @@ -118,7 +119,7 @@ for (const staleLegacyTerm of [ } const pullRequestTemplate = await readFile(".github/pull_request_template.md", "utf8"); -for (const expected of ["Owner And Impact", "Architecture And AI-Assisted Review", "CONTRIBUTING.md"]) { +for (const expected of ["Owner And Impact", "Architecture Notes", "pnpm check:architecture", "CONTRIBUTING.md"]) { if (!pullRequestTemplate.includes(expected)) { throw new Error(`Pull request template is missing expected guidance: ${expected}.`); }