From 1d595aabed73ec5b6a88d769afa56ec63087b218 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:42:34 +0000 Subject: [PATCH 1/2] docs: make "work from dev" an explicit mandatory rule Both instruction files referenced dev in passing - experimental code stays out of it, it carries the next version after a promotion, docs deploy from it - but neither ever said to START from it. An agent could read all of CLAUDE.md, come away knowing dev exists and matters, and still baseline its work on main. That is exactly what happened during the media-initiative planning pass: every file anchor and architectural claim was researched against main 1.5.0, and dev turned out to be 305 commits and a minor version ahead, carrying an entire model-registry subsystem the research never saw. The findings had to be re-verified and the documents re-baselined. It was luck rather than judgment that the speech surface had not moved. Adds it as the first rule under Mandatory Workflow Rules in both CLAUDE.md and AGENTS.md: cut branches from dev, open pull requests against dev, read dev when you need current truth, and say which branch you checked when a claim matters. Includes the fetch/checkout command and names the concrete failure mode so the rule carries its own justification. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KByyiUEiVSY3eDvrWbqDDi --- AGENTS.md | 21 +++++++++++++++++++++ CLAUDE.md | 21 +++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3959c82e..86b42314 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -240,6 +240,27 @@ Centralized logging uses a three-layer stack: These rules apply to every change. No exceptions. +### Work from `dev`, always + +`dev` is the baseline for every change. Cut branches from it, open pull +requests against it, and read it whenever you need current truth: + +```bash +git fetch origin dev && git checkout -b origin/dev +``` + +`main` is the release branch and trails `dev` by an entire release cycle - +routinely hundreds of commits. Anything read from `main` may therefore be +stale: file paths and line anchors, where a function lives, which subsystems +exist at all, and whether an architectural claim still holds. This is a +recorded failure mode, not a theoretical one - a planning pass was once +researched entirely against `main` and had to be redone when `dev` turned out +to be 305 commits and a minor version ahead, with a whole subsystem the +research never saw. + +So: when a claim about this codebase matters, verify it on `dev`, and say which +branch you checked. + ### Experimental code stays out of dev Unproven, demo-bound, or design-in-motion work never merges to dev. It lives diff --git a/CLAUDE.md b/CLAUDE.md index aa64b7c4..2caa1e67 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -587,6 +587,27 @@ peer APIs rather than through a central authoritative trace store. These rules apply to every change. No exceptions. +### Work from `dev`, always + +`dev` is the baseline for every change. Cut branches from it, open pull +requests against it, and read it whenever you need current truth: + +```bash +git fetch origin dev && git checkout -b origin/dev +``` + +`main` is the release branch and trails `dev` by an entire release cycle - +routinely hundreds of commits. Anything read from `main` may therefore be +stale: file paths and line anchors, where a function lives, which subsystems +exist at all, and whether an architectural claim still holds. This is a +recorded failure mode, not a theoretical one - a planning pass was once +researched entirely against `main` and had to be redone when `dev` turned out +to be 305 commits and a minor version ahead, with a whole subsystem the +research never saw. + +So: when a claim about this codebase matters, verify it on `dev`, and say which +branch you checked. + ### Experimental code stays out of dev Unproven, demo-bound, or design-in-motion work never merges to dev. It lives From 390495cab0dc6f73dfdb79a355923c1d0c4d152c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 18 Aug 2026 12:46:26 +0000 Subject: [PATCH 2/2] docs: exempt release promotion from the dev rule, cite CONTRIBUTING.md Review caught a real conflict I introduced. The new rule said "open pull requests against dev" and sits under a heading reading "These rules apply to every change. No exceptions." CONTRIBUTING.md's Branching Model requires promotion pull requests from dev to main at a release cut, so an agent following the new rule literally could not perform the documented release workflow. Scoped the rule to day-to-day work and named the exception: promotion PRs from dev to main are opened by maintainers. Verifying that citation turned up something more useful. CONTRIBUTING.md already carried this convention - "Day-to-day work branches from dev and merges back to dev via pull request... Open pull requests against dev (the repository default)". The rule was documented all along; it simply was not in the files an agent actually reads, which is why a planning pass could baseline on main without ever contradicting anything it had been told. So this change is better understood as propagating an existing rule into the agent instruction files than as inventing a new one. Both copies now say so and link CONTRIBUTING.md as the origin, with a note to keep the two in step, so the restatement cannot silently drift from the source. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01KByyiUEiVSY3eDvrWbqDDi --- AGENTS.md | 7 ++++++- CLAUDE.md | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 86b42314..1711bab7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -242,7 +242,7 @@ These rules apply to every change. No exceptions. ### Work from `dev`, always -`dev` is the baseline for every change. Cut branches from it, open pull +`dev` is the baseline for day-to-day work. Cut branches from it, open pull requests against it, and read it whenever you need current truth: ```bash @@ -261,6 +261,11 @@ research never saw. So: when a claim about this codebase matters, verify it on `dev`, and say which branch you checked. +The one exception is the release cut itself: promotion pull requests from `dev` +to `main` are opened by maintainers. This rule restates, for agents, the +branching model already documented in +[`CONTRIBUTING.md`](CONTRIBUTING.md) - keep the two in step if either changes. + ### Experimental code stays out of dev Unproven, demo-bound, or design-in-motion work never merges to dev. It lives diff --git a/CLAUDE.md b/CLAUDE.md index 2caa1e67..39016478 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -589,7 +589,7 @@ These rules apply to every change. No exceptions. ### Work from `dev`, always -`dev` is the baseline for every change. Cut branches from it, open pull +`dev` is the baseline for day-to-day work. Cut branches from it, open pull requests against it, and read it whenever you need current truth: ```bash @@ -608,6 +608,11 @@ research never saw. So: when a claim about this codebase matters, verify it on `dev`, and say which branch you checked. +The one exception is the release cut itself: promotion pull requests from `dev` +to `main` are opened by maintainers. This rule restates, for agents, the +branching model already documented in +[`CONTRIBUTING.md`](CONTRIBUTING.md) - keep the two in step if either changes. + ### Experimental code stays out of dev Unproven, demo-bound, or design-in-motion work never merges to dev. It lives