From 5aa6368ed47b489b1b300080bf595800098fa86d Mon Sep 17 00:00:00 2001 From: reachableceo Date: Mon, 10 Aug 2026 09:18:31 -0500 Subject: [PATCH] docs(rules): add cross-referencing and sync mandates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three new rules added to AGENTS.md and BASELINE-PROMPT.md: 1. Code/docs/tests must be kept in sync at all times — update all three in the same commit when making changes. 2. Redmine and Discourse must cross-reference each other — every ticket links to its Discourse doc and vice versa. 3. Commits must reference Redmine tickets ([#NNN]); PRs must link to both Redmine and Discourse. 💘 Generated with Crush Assisted-by: Crush --- AGENTS.md | 12 ++++++++++++ BASELINE-PROMPT.md | 3 +++ 2 files changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7dc5f81..8ca1f37 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,6 +82,13 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \ - **Discourse**: synthesized decisions, runbooks, architecture docs, audit logs, reference material. - Working notes → Redmine; synthesize durable knowledge → Discourse. +### Cross-referencing (mandatory) +- **Every Redmine ticket must link to its Discourse doc** (if one exists or is created) in a note or description. +- **Every Discourse topic must link to its related Redmine ticket(s)** in the body. +- **Every commit must reference the Redmine ticket** (`[#NNN]` in the subject or body). +- **Every PR must link to both** the Redmine ticket and the Discourse doc (if applicable) in the PR body. +- When a ticket is created or updated, add a Discourse link. When a Discourse doc is created or updated, add ticket links. Keep them in sync at all times. + ## Git Workflow - **Use the `tea` CLI for pull requests** (`tea` and `docker login` are preconfigured on TSYS workstations). @@ -103,6 +110,7 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \ Assisted-by: via ``` Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `security`. +- **Commit/PR cross-linking:** every commit subject or body must reference the Redmine ticket (`[#NNN]`). Every PR body must link to both the Redmine ticket and the Discourse doc (if one exists). - **Never interrupt current work** when the human tosses new work mid-task. Log it in the **Inbox** section of `STATUS.md`. If materially different, spin up a Redmine ticket. ## Task Tracking @@ -173,6 +181,7 @@ Bypass with `--no-verify` in genuine emergencies only. ## TDD & Linting +- **Code, docs, and tests must be kept in sync at all times.** When you change code, update the corresponding docs (Discourse) and tests in the same commit. Never leave them out of sync. - **Red/green TDD for all code.** Write the failing test first. - **Linters on all code, as early as possible.** Let deterministic tools find the issues. @@ -184,6 +193,9 @@ Bypass with `--no-verify` in genuine emergencies only. - Run `bash scripts/check-rules.sh` before committing. - Use sub-agents to parallelize scoped work. - Log interruptions to the STATUS.md Inbox. +- Keep code, docs, and tests in sync within the same commit. +- Cross-reference Redmine ↔ Discourse on every ticket/doc creation or update. +- Include `[#NNN]` in every commit; link Redmine + Discourse in every PR. ## DO NOT diff --git a/BASELINE-PROMPT.md b/BASELINE-PROMPT.md index 10899f5..994bbfe 100644 --- a/BASELINE-PROMPT.md +++ b/BASELINE-PROMPT.md @@ -31,6 +31,8 @@ - **Discourse is the single system of record for documentation.** It is all Markdown. Use the `discourse-cli` tool. Do not author long-form docs in gitea. - **Git-tracked `.md` files should be stubs** that point to the relevant Discourse URL. Short operational files that must live next to code (e.g. `AGENTS.md`, `STATUS.md`) are the exception. - Engineering already works this way. Operations now does too. +- **Cross-referencing is mandatory.** Every Redmine ticket links to its Discourse doc; every Discourse doc links to its Redmine ticket(s); every commit references `[#NNN]`; every PR links to both Redmine and Discourse. Keep them in sync at all times. +- **Code, docs, and tests must be kept in sync at all times.** When you change code, update the corresponding docs (Discourse) and tests in the same commit. Never leave them out of sync. ## 4. Git workflow @@ -38,6 +40,7 @@ - **Work smart off master** generally. Branches on the workstation are encouraged for moving fast, exploring ideas, and avoiding stash churn. - **Once work leaves the workstation, it goes through a PR.** - Branching strategy is open to per-project discussion. +- **Commits and PRs must cross-link** to Redmine tickets (`[#NNN]` in subject or body) and Discourse docs (in PR body). ## 5. CI/CD — shift left, keep in lockstep