From a083a919c1b07529a756b635829aa536e606ada8 Mon Sep 17 00:00:00 2001 From: Esteban Gaviria Zambrano Date: Sun, 30 Aug 2026 17:36:58 -0500 Subject: [PATCH 1/3] docs(agents): adopt the binding delivery conventions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds `.github/pull_request_template.md` and the Conventions entries that bind every contributor, agents included, to `microservice-app-docs/docs/Pull request and task tracking conventions.md`. The rule that was missing: every task completed is marked in the same pull request that completed it, and only against a located artifact — never from a summary, a green check, or a rendered manifest. Spec 007 sat at 0/27 while twenty-one of its tasks were already delivered and merged; that is what this prevents. Also binds the pull-request format itself, keeps the `test(scope): specify` -> `feat(scope): implement` pair intact as SDD evidence, and states plainly that an AI agent may open and update a pull request but may never approve one or author an acceptance artifact. Constitution principle 13 (Traceable Delivery), drafted in microservice-app-docs, is what makes this non-negotiable. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01NLzNfeedbe2xFTjwrBPPBg --- .github/pull_request_template.md | 60 ++++++++++++++++++++++++++++++++ AGENTS.md | 6 ++++ 2 files changed, 66 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..e6cf68a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,60 @@ + + +## What changes + + + +## Why + + + +## Tasks + + + +- [ ] The task register is updated in this pull request +- [ ] Every task ticked here was verified by locating its artifact + +## How it is verified + + + +## Risk and rollback + + + +## What this PR does not do + + + +--- + + diff --git a/AGENTS.md b/AGENTS.md index b617bb8..5b5a805 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,12 @@ It exposes Prometheus metrics, reports traces to Zipkin, and publishes create/de - Todo state is keyed by `req.user.username`; a new user receives three seeded items, and mutations are explicitly not concurrency-safe. - `/metrics` is registered before JWT middleware and is public; all `/todos` routes require a JWT bearer token. - The API has no update route, and only create/delete operations publish Redis messages containing the Zipkin trace ID. +- Open every pull request through `.github/pull_request_template.md` and follow `microservice-app-docs/docs/Pull request and task tracking conventions.md`: one concern per short-lived `/` branch, a Conventional Commit title with a scope, and every template section filled. Constitution principle 13 makes this binding, not advisory. +- Keep the Spec-Driven Development commit pair intact: `test(): specify ...` must be committed failing before `feat(): implement ...`. Never squash the pair; the failing-test commit is the evidence the cycle was followed. +- Track every task. Name in the pull-request body the task IDs it advances, qualified by repository and spec, and update `tasks.md` in that same pull request rather than a follow-up. Mark a task `[X]` only after locating and inspecting its named artifact — never from a summary, a green check, a rendered manifest, or recollection. Annotate partial delivery instead of ticking it; work no register covers either gains a task or records in the PR body why none applies. +- Reconcile, never quietly edit, when a register and reality disagree: a specification that pins a version nobody shipped is a maintainer decision, and `microservice-app-docs/full-platform/plan-reconciliation.md` is the worked example. +- Never merge with `--admin`, force-push to `main`, disable a branch protection rule to land your own work, or approve your own pull request. As an AI agent you may open, describe, and update a pull request; you may never approve one and never author an acceptance or approval artifact — only a named human unlocks a gate. +- Report outcomes faithfully in commits and pull-request bodies: name what is red, say what was skipped, and correct an earlier claim that turns out to be wrong rather than leaving the record wrong. ## Notes for the Kubernetes migration - The service listens on `TODO_API_PORT` (default `8082`) and serves `/metrics` on the same port. From 53b21337781f0fded7dbf40fa77d9b2696000481 Mon Sep 17 00:00:00 2001 From: Esteban Gaviria Zambrano Date: Sun, 30 Aug 2026 18:18:35 -0500 Subject: [PATCH 2/3] docs(agents): state that pull requests are written in English The template listed the required sections and never said what language to write them in. The omission had an immediate consequence: the pull requests that introduced these conventions had Spanish bodies while their commits and files were English. Mirrors section 3 of the conventions, added in microservice-app-docs. --- .github/pull_request_template.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6cf68a..c8f0b36 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,6 +7,10 @@ Every section below is required. Where one genuinely does not apply, write Title: the same Conventional Commit string as the primary commit, e.g. feat(us3): implement the auth-api operational contract + +Written in English — title, body, and review comments. See section 3 of the +conventions. Discussing the change in another language is fine; writing it into +the repository is not. --> ## What changes From b56db94838dc8f9bf926d57550ff9e612fbaaca3 Mon Sep 17 00:00:00 2001 From: Esteban Gaviria Zambrano Date: Sun, 30 Aug 2026 18:31:14 -0500 Subject: [PATCH 3/3] docs(agents): adopt bilingual pull-request bodies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirrors section 3 of the conventions: the body is written in English and then repeated under a Spanish heading with the same content. Titles, commits, code comments, and documentation stay English-only. Applies to AI agents too — an agent writes both halves itself. --- .github/pull_request_template.md | 14 +++++++++++--- AGENTS.md | 1 + 2 files changed, 12 insertions(+), 3 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c8f0b36..d38f2a0 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,9 +8,11 @@ Every section below is required. Where one genuinely does not apply, write Title: the same Conventional Commit string as the primary commit, e.g. feat(us3): implement the auth-api operational contract -Written in English — title, body, and review comments. See section 3 of the -conventions. Discussing the change in another language is fine; writing it into -the repository is not. +Language: the TITLE is English (it becomes the squash-merge commit subject). +The BODY is bilingual — write every section in English, then repeat it under a +`## Español` heading. Same content, not a summary. See section 3. +This applies to AI agents too: write both halves, do not leave one for someone +else. --> ## What changes @@ -62,3 +64,9 @@ the repository is not. not author an acceptance artifact. - Report faithfully: if CI is red, say what is red. If a step was skipped, say it was skipped. --> + +--- + +## Español + + diff --git a/AGENTS.md b/AGENTS.md index 5b5a805..a8c3a75 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,7 @@ It exposes Prometheus metrics, reports traces to Zipkin, and publishes create/de - Todo state is keyed by `req.user.username`; a new user receives three seeded items, and mutations are explicitly not concurrency-safe. - `/metrics` is registered before JWT middleware and is public; all `/todos` routes require a JWT bearer token. - The API has no update route, and only create/delete operations publish Redis messages containing the Zipkin trace ID. +- Write pull-request bodies bilingually: every section in English, then repeated under a `## Español` heading with the same content, not a summary. Titles, commits, code comments, documentation, and specification text stay English-only. As an AI agent you write both halves yourself. - Open every pull request through `.github/pull_request_template.md` and follow `microservice-app-docs/docs/Pull request and task tracking conventions.md`: one concern per short-lived `/` branch, a Conventional Commit title with a scope, and every template section filled. Constitution principle 13 makes this binding, not advisory. - Keep the Spec-Driven Development commit pair intact: `test(): specify ...` must be committed failing before `feat(): implement ...`. Never squash the pair; the failing-test commit is the evidence the cycle was followed. - Track every task. Name in the pull-request body the task IDs it advances, qualified by repository and spec, and update `tasks.md` in that same pull request rather than a follow-up. Mark a task `[X]` only after locating and inspecting its named artifact — never from a summary, a green check, a rendered manifest, or recollection. Annotate partial delivery instead of ticking it; work no register covers either gains a task or records in the PR body why none applies.