diff --git a/rules/patterns/git-sync-check/contract.md b/rules/patterns/git-sync-check/contract.md index 0019a77..d9921e6 100644 --- a/rules/patterns/git-sync-check/contract.md +++ b/rules/patterns/git-sync-check/contract.md @@ -3,20 +3,39 @@ ## Rule Before starting any work on a task, check whether the remote repository has commits that are not yet present locally. +This rule assumes the repository is hosted in Gitea. +Use neutral `git` commands for sync checks and branch management, and use Gitea terminology for server-side review flow (`pull request`, not `merge request`). ## Required Steps -1. Run `git fetch` to update remote-tracking refs without merging. +1. Run `git fetch origin` to update remote-tracking refs from the Gitea remote without merging. 2. Check for upstream commits: `git log HEAD..@{u} --oneline`. 3. If the output is non-empty (there are new remote commits): - **Stop immediately. Do not make any changes.** - Inform the user that the remote has new commits and ask how to proceed (e.g., pull, rebase, or ignore). 4. If the output is empty, proceed with the task normally. +## Gitea Workflow Notes + +- Verify the remote when needed: `git remote -v` +- Create a task branch before changes: `git checkout -b ` +- Push the branch to Gitea and set upstream: `git push -u origin ` +- Open the review in Gitea as a pull request against the target branch. +- If the `tea` CLI is configured for the environment, it may be used for Gitea pull request actions such as: + - `tea pr list` + - `tea pr create` + - `tea pr checkout ` + +## Forbidden Assumptions + +- Do not assume GitHub-specific tooling such as `gh`. +- Do not use GitLab terminology such as `merge request` unless a project explicitly defines that workflow separately. +- Do not replace the required sync check with web UI inspection in Gitea; the local `git fetch origin` and `git log HEAD..@{u} --oneline` check remains mandatory. + ## Rationale -Working on an outdated local state risks merge conflicts, duplicate work, and overwriting changes made by other contributors. Checking remote state first keeps the working tree aligned and prevents avoidable conflicts. +Working on an outdated local state risks merge conflicts, duplicate work, and overwriting changes made by other contributors. Checking remote state first keeps the working tree aligned and prevents avoidable conflicts. Using Gitea-specific review terminology and examples also avoids workflow confusion in repositories that are not hosted on GitHub or GitLab. ## Exceptions -- Offline environments where `git fetch` is not possible: notify the user that the check could not be performed before proceeding. +- Offline environments where `git fetch origin` is not possible: notify the user that the check could not be performed before proceeding. diff --git a/rules/patterns/go-code-style/contract.md b/rules/patterns/go-code-style/contract.md index f11b9cd..7de4eb9 100644 --- a/rules/patterns/go-code-style/contract.md +++ b/rules/patterns/go-code-style/contract.md @@ -2,6 +2,13 @@ Version: 1.1 +## Source Text and Comments + +- Use plain ASCII in source code and comments by default. +- Do not use em dash, emoji, or other decorative Unicode markers in code, comments, log messages, or user-facing fallback strings unless a feature explicitly requires non-ASCII text. +- Do not leave AI-style markers in the codebase: ornamental phrasing, assistant-like filler, synthetic enthusiasm, or comments that read like generated prose instead of technical documentation. +- Comments must be short, concrete, and technical. Explain intent, invariants, or non-obvious constraints; do not write marketing-style or conversational commentary. + ## Logging See `kit/patterns/go-logging/contract.md` for full rules. @@ -18,7 +25,7 @@ if err := db.Save(&record).Error; err != nil { return fmt.Errorf("save component %s: %w", record.ID, err) } -// WRONG — loses context +// WRONG: loses context return err ``` @@ -35,9 +42,9 @@ return err Handlers are thin. Business logic belongs in a service layer. ``` -Handler → validates input, calls service, writes response -Service → business logic, calls repository -Repository → SQL queries only, returns domain types +Handler -> validates input, calls service, writes response +Service -> business logic, calls repository +Repository -> SQL queries only, returns domain types ``` - Handlers must not contain SQL queries. @@ -48,7 +55,7 @@ Repository → SQL queries only, returns domain types ``` 1. Parse flags / load config -2. Connect to DB — fail fast if unavailable (see go-database contract) +2. Connect to DB; fail fast if unavailable (see go-database contract) 3. Run migrations 4. Initialize services and background workers 5. Register routes @@ -69,14 +76,14 @@ Never reverse steps 2 and 5. Never start serving before migrations complete. ## Template / UI Rendering - Server-rendered HTML via Go templates is the default. -- htmx for partial updates — no full SPA framework unless explicitly decided. +- htmx for partial updates; no full SPA framework unless explicitly decided. - Template errors must return `500` and log the error server-side. - Never expose raw Go error messages to the end user in rendered HTML. ## Business Logic Placement - Threshold computation, status derivation, and scoring live on the server. -- The UI only reflects what the server returns — it does not recompute status client-side. +- The UI only reflects what the server returns; it does not recompute status client-side. - Example: "critical / warning / ok" badge color is determined by the handler, not by JS. ## Dependency Rules diff --git a/rules/patterns/go-project-bible/contract.md b/rules/patterns/go-project-bible/contract.md index 0dd8ee5..d1b86c6 100644 --- a/rules/patterns/go-project-bible/contract.md +++ b/rules/patterns/go-project-bible/contract.md @@ -16,29 +16,29 @@ Every project bible must have these files: ``` bible-local/ - README.md — index: what files exist and what each covers + README.md - index: what files exist and what each covers architecture/ - system-overview.md — what the product does, active scope, non-goals - data-model.md — domain entities, DB tables, naming conventions - api-surface.md — all HTTP endpoints with methods and response shape - runtime-flows.md — key mutation flows, invariants, critical rules + system-overview.md - what the product does, active scope, non-goals + data-model.md - domain entities, DB tables, naming conventions + api-surface.md - all HTTP endpoints with methods and response shape + runtime-flows.md - key mutation flows, invariants, critical rules decisions/ - README.md — ADL format explanation - YYYY-MM-DD-topic.md — one file per architectural decision + README.md - ADL format explanation + YYYY-MM-DD-topic.md - one file per architectural decision ``` Optional (add when relevant): ``` architecture/ - ui-information-architecture.md — page structure, navigation, UI invariants + ui-information-architecture.md - page structure, navigation, UI invariants docs/ - INTEGRATION_GUIDE.md — external system integration (formats, protocols) + INTEGRATION_GUIDE.md - external system integration (formats, protocols) ``` ## system-overview.md Rules - List what is **in scope** and what is **explicitly out of scope**. -- Out of scope section prevents scope creep — update it when you reject a feature. +- Out of scope section prevents scope creep; update it when you reject a feature. - Include tech stack and local run command. ## data-model.md Rules @@ -63,7 +63,7 @@ This is the most important file. Document flows that are **easy to break**: - Event/time source priority rules - Deduplication logic - Cross-entity side effects (e.g. removing a component affects asset status) -- Anything that caused a bug or regression — add a "DO NOT reintroduce" note +- Anything that caused a bug or regression: add a "DO NOT reintroduce" note Format each flow as a numbered list of steps, not prose. @@ -94,19 +94,20 @@ What this means going forward. What is now forbidden or required. ``` - One decision per file, named `YYYY-MM-DD-short-topic.md`. -- When a decision is superseded, add `superseded by` to the old file's status — do not delete it. +- When a decision is superseded, add `superseded by` to the old file's status; do not delete it. - Record the decision **in the same commit** as the code that implements it. ## What NOT to Put in bible-local/ -- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/` -- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder +- Generic rules (CSV format, logging, pagination) -> these are in `bible/rules/patterns/` +- Work-in-progress notes, TODO lists -> use issues or a separate `docs/` folder - Duplicate of what is already in code (don't restate what the code clearly shows) -- Speculative future architecture — document what exists, not what might exist +- Speculative future architecture: document what exists, not what might exist ## Keeping the Bible Current - Update `bible-local/` in the **same commit** as the code change it describes. - If you change a flow, update `runtime-flows.md` in the same PR. -- If a section becomes outdated, fix or delete it — stale docs are worse than no docs. +- If a section becomes outdated, fix or delete it; stale docs are worse than no docs. - Bible files are in **English only**. +- Do not use em dash in Bible files; prefer ASCII punctuation such as `-`, `:`, or `;` depending on the sentence.