Clarify documentation structure and governance

[marcuscastelo]

Enhance the clarity of the documentation by establishing a canonical structure and governance while providing context on Dependency Injection patterns and repository usage. This update aims to improve the overall understanding and accessibility of architectural decisions within the project.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
macroflows	Ready	Preview, Comment	Mar 25, 2026 0:26am

[Copilot]

Pull request overview

Establishes a canonical documentation structure and governance model (with ADRs and doc status banners), and enforces it via a new docs:check script integrated into the repository quality gate.

Changes:

• Add canonical docs (AGENTS.md, docs/ARCHITECTURE.md, docs/BOUNDARIES.md, docs/DOCS_GOVERNANCE.md, ADR set) and a canonical docs/README.md index.
• Convert tool-specific instruction entrypoints (Claude/Gemini/Copilot) into pointer docs and label historical/audit docs as supporting/archived via status banners.
• Add scripts/check-doc-governance.mjs and run it as part of pnpm check (docs:check).

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
scripts/check-doc-governance.mjs	New governance validator for canonical/pointer/supporting/archived doc contract.
package.json	Adds docs:check and runs it as part of pnpm check.
README.md	Adds a “Project Docs” section linking to canonical docs/ADRs.
AGENTS.md	Introduces canonical repo-wide agent entrypoint and precedence/command defaults.
CLAUDE.md	Converts to a Claude-specific pointer to AGENTS.md.
GEMINI.md	Converts header to pointer-to-canon structure (but still contains substantial policy content).
.github/copilot-instructions.md	Converts to Copilot pointer/transport file pointing to AGENTS.md.
.github/README.md	Adds supporting-doc banner + explains .github/ assets/governance.
.github/COPILOT_SETUP_VALIDATION.md	Reframes as supporting snapshot; updates claims about “main instruction file”.
.github/copilot-commit-message-instructions.md	Labels as supporting doc; clarifies non-canonical status.
.github/prompts/refine-github-issue.prompt.md	Updates references from copilot-instructions.md to AGENTS.md.
.github/prompts/refactor.prompt.md	Updates quality gate guidance to pnpm check; points global rules to AGENTS.md.
.github/prompts/pr-reviews.prompt.md	Updates workflow steps from legacy Copilot gate to pnpm check + canonical docs.
.github/prompts/issues-worktree.prompt.md	Updates references from copilot-instructions.md to AGENTS.md.
.github/prompts/code-review.prompt.md	Updates global-rules reference to AGENTS.md; normalizes reportedBy placement.
docs/README.md	Adds canonical documentation index by status (canonical/pointer/supporting/archived).
docs/DOCS_GOVERNANCE.md	Adds canonical governance policy for doc lifecycle/status/precedence/enforcement.
docs/ARCHITECTURE.md	Adds canonical “current state” architecture map (modules/sections/shared/routes/di).
docs/BOUNDARIES.md	Adds canonical dependency/ownership rules by layer and top-level area.
docs/adr/README.md	Adds canonical ADR rules, template pointer, and index list.
docs/adr/_template.md	Adds ADR template with “Canon Sync” section.
docs/adr/0001-canonical-agent-instructions-and-doc-precedence.md	Records decision to centralize canon + make tool files pointers.
docs/adr/0002-current-repo-architecture-and-boundaries.md	Records current architecture/boundaries reality (incl. diet macro-context).
docs/adr/0003-error-handling-and-simplification-defaults.md	Records standardized defaults (pnpm check, Error usage, simplification).
docs/COPILOT_SHORT_GUIDE.md	Reframes as supporting Copilot guidance; points to AGENTS.md.
docs/ARCHITECTURE_GUIDE.md	Marks as supporting and updates DI guidance to match current repo pattern.
docs/CODESTYLE_GUIDE.md	Marks as supporting with banner.
docs/ARCHITECTURE_AUDIT.md	Marks as supporting with banner.
docs/audit_domain.md	Marks as supporting with banner.
docs/audit_domain_diet.md	Marks as supporting with banner.
docs/audit_domain_diet_food.md	Marks as supporting with banner.
docs/audit_domain_diet_recipe.md	Marks as supporting with banner.
docs/audit_sections.md	Marks as supporting with banner.
docs/RECIPE_MIGRATION_AUDIT.md	Marks as supporting with banner.
docs/DEPRECATION_PLAN_V0.14.0.md	Marks as supporting with banner.
DI-migration-plan.md	Marks as supporting with banner.
docs/archive/TODO-REPO-DOC.md	Marks as archived with banner and canonical pointers.

Comments suppressed due to low confidence (1)

GEMINI.md:21

• This file is marked as Doc status: pointer., but it still contains a large amount of repo policy and implementation guidance below the pointer header. That conflicts with the governance rule that pointer docs should be thin entrypoints and must not compete with canonical docs. Consider moving the remaining guidance to a supporting doc (or into canonical docs where appropriate) and keeping this file as a short pointer to AGENTS.md.

## Gemini-specific notes

- Gemini transport and MCP configuration for this repo live in `.gemini/settings.json`.
- Use the canonical workflow and command defaults from `AGENTS.md`.
- **NO `any`:** The use of `any`, `as any`, or `@ts-ignore` is strictly forbidden outside the Infrastructure layer. This ensures strong type safety and reduces the need for redundant runtime type checks in tests.
- **`type` over `interface`:** Always use type aliases for defining data shapes.
- **Readonly:** Prefer `readonly Item[]` over `Item[]` for immutability.
- **Props Immutability:** **NEVER** destructure `props` in SolidJS components, as it breaks reactivity.