From a170693c1aeb3ffbd3bf3826c25c9a80203e45e9 Mon Sep 17 00:00:00 2001 From: "Claude (Emil)" Date: Tue, 10 Nov 2026 13:29:41 +0000 Subject: [PATCH 1/3] docs(adr): ADR 0241, a commit message never names a model; its identifier is allowed The maintainer's ruling of 2026-10-27, which #169's gate implements, reverses the commit-message half of ADR 0033's amendment of 2026-10-02. A reversal is a change of meaning, so under ADR 0068 point 2 it is a supersession: ADR 0241 supersedes that one ruling, and ModelNamedInTheRecordNotTheCommit moves to 0241's set under its key, filed unaccepted (ADR 0066). 0033's Status names the supersession, and AGENTS.md (Every commit, Never) and CONTRIBUTING.md state the ruling. The record still names the tool and the model exactly. Refs #257 Refs #169 Co-Authored-By: Claude Signed-off-by: Emil Okkels Klein --- AGENTS.md | 13 +-- CONTRIBUTING.md | 4 +- docs/adr/0033-commit-traceability.md | 5 ++ ...model-names-refused-identifiers-allowed.md | 90 +++++++++++++++++++ docs/adr/README.md | 8 ++ docs/decisions/commit-traceability.md | 9 +- ...model-names-refused-identifiers-allowed.md | 13 +++ 7 files changed, 128 insertions(+), 14 deletions(-) create mode 100644 docs/adr/0241-model-names-refused-identifiers-allowed.md create mode 100644 docs/decisions/model-names-refused-identifiers-allowed.md diff --git a/AGENTS.md b/AGENTS.md index 8f5ae498..659e304c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -159,10 +159,11 @@ Conventional commits, one logical change each, and three things in each: exactly**, and the report. The model is the identifier the session's metadata reports. A tool that will not write it says so in the record, and the maintainer fills it in: a blank model is an incomplete record. **A commit message never -carries a model's identifier** (the string an API takes to select a model); a -tool's co-author trailer naming the product is not one (ADR 0033, amended -2026-10-02). Prose says "developed with AI assistance under human review" and -**names no product**. +carries a model's name** (a family word, alone or after the product, followed +by a version); a model's identifier (the string an API takes to select a +model) is allowed, and so is a co-author trailer naming only the product +(ADR 0241, superseding ADR 0033's amendment of 2026-10-02). Prose says +"developed with AI assistance under human review" and **names no product**. ## `Varve.Store` behaviour @@ -541,8 +542,8 @@ exists. - A native dependency, or any package that ships a native asset. - `System.Uri` where an IRI is meant. Use `Varve.Iri` (ADR 0004). - A commit with no issue reference or no DCO sign-off, or one whose message - carries a model's identifier; a long-lived branch; a trunk left - un-releasable. + carries a model's name (its identifier is allowed, ADR 0241); a long-lived + branch; a trunk left un-releasable. - Reflection, `Reflection.Emit` or `dynamic` in shipped code. - A `Common` / `Core` / `Utils` / `Abstractions` package, or an upward or same-layer reference. A `.cs` file without the MPL-2.0 notice (ADR 0031). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 64599e4f..159a748a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -162,7 +162,9 @@ and tied to issues ([ADR 0033](docs/adr/0033-commit-traceability.md)). and the model, named exactly**, and the report it returned. The model is the identifier the session's metadata reports; where the tool will not write it, the record says so and the maintainer fills it in. A commit message never -carries a model's identifier (ADR 0033, amended 2026-10-02). +carries a model's name; a model's identifier is allowed, and so is a co-author +trailer naming only the product (ADR 0241, superseding ADR 0033's amendment of +2026-10-02). Prose in `README.md`, `CONTRIBUTING.md`, `GOVERNANCE.md` and the documentation describes the project as developed with AI assistance under human review and diff --git a/docs/adr/0033-commit-traceability.md b/docs/adr/0033-commit-traceability.md index 2ec3b9e1..319ffe52 100644 --- a/docs/adr/0033-commit-traceability.md +++ b/docs/adr/0033-commit-traceability.md @@ -13,6 +13,11 @@ the records. under *The wording rule splits*: what "named exactly" means for the model, and that a commit message never carries a model's identifier. +**Superseded in part by [0241](0241-model-names-refused-identifiers-allowed.md)** +(filed 2026-11-10): the amendment's ruling on the commit message is reversed. +A commit message never names a model, and a model's identifier is allowed. The +record still names the model exactly. + ## Context The Mind Over Machine stewardship standard asks for one thing under this diff --git a/docs/adr/0241-model-names-refused-identifiers-allowed.md b/docs/adr/0241-model-names-refused-identifiers-allowed.md new file mode 100644 index 00000000..d9122750 --- /dev/null +++ b/docs/adr/0241-model-names-refused-identifiers-allowed.md @@ -0,0 +1,90 @@ +# 0241 — A commit message never names a model; a model's identifier is allowed + +## Status + +**Filed unaccepted by the session for #257, 2026-11-10** (ADR 0066). Decided +by the maintainer on 2026-10-27, in the scope of +[#169](https://github.com/Hafeok/Varve/issues/169). Acceptance is the +maintainer's act, or his delegate's for a decision he has read (ADR 0239). + +**Supersedes one ruling of [0033](0033-commit-traceability.md)**, +`ModelNamedInTheRecordNotTheCommit`, as its amendment of 2026-10-02 stated it. +The half about the record is restated here unchanged; the half about the +commit message is reversed. Under ADR 0068 point 2, that reversal is a change of +meaning, so it is a supersession, not an amendment. The ruling moves to this +ADR's set under the same key (ADR 0068 point 4). + +## Context + +ADR 0033's amendment of 2026-10-02 said a commit message never carries a +model's *identifier*, the string a provider's API takes to select a model, +and allowed a co-author trailer that names the product. Its reason was that a +commit message cannot be corrected without rewriting the trunk (ADR 0032), +and the record is where the fact can be corrected. + +In practice the trailer did the opposite. The tool these sessions use writes a +co-author trailer that names the model by its marketing name, family and +version (`Claude Opus 5.5`). `main` carried 241 such commits by 2026-10-27, +all signed and merged, so they stay. The name was in the commit, and the +identifier was barred. The identifier is what a reader can resolve exactly +and what the record holds; a name is the form that drifts and gets +advertised. + +On 2026-10-27 the maintainer ruled the other way round, for #169's gate: +**names refused, identifiers allowed.** `AGENTS.md` and `CONTRIBUTING.md` +still said the reverse, and a gate built to the ruling would contradict an +accepted decision. This ADR records the ruling so that the gate, the rule +files and the ledger agree. + +## Decision + +1. **A commit message never carries a model's name.** A name is a model + family word (`Opus`, `Sonnet`, `Haiku`, `Fable`, `Mythos`, and any family + the gate's configuration adds), alone or after `Claude`, followed by a + version: `Opus 5.5`, `Claude Sonnet 5.5`. The rule covers the subject, the + body and every trailer. +2. **A model's identifier is allowed**, in the API form a provider takes + (`claude---`), as is the bare product name in a co-author trailer: + `Co-Authored-By: Claude `. +3. **The traceability record still names the tool and the model exactly**, + unchanged from 0033's amendment: the model is the identifier the session's + metadata reports. Where the tool will not write it into a pushed file, the + record says so where the model belongs and the maintainer fills it in. A + blank model is an incomplete record. +4. **History is left as it is.** #169's gate checks the commits a pull + request or a `land/` branch adds over `main`, never `main`'s history. + +## Alternatives considered + +- **Amend 0033 instead.** Rejected: ADR 0068 point 2 makes a change of meaning + a supersession, and this reverses which form is allowed. +- **Refuse both names and identifiers.** Rejected by the maintainer's ruling. + An identifier in a commit is harmless and exact. Refusing it would also + refuse the one form a tool can write mechanically from its own metadata. +- **Keep 0033's rule and fix the trailer.** Not chosen. It leaves the rule + barring the precise form and allowing nothing that says which model wrote + the commit, while the gate that would enforce it does not exist. + +## Consequences + +- **`AGENTS.md` and `CONTRIBUTING.md` change with this ADR.** **Every + commit** and **Never** state the ruling, and so does `CONTRIBUTING.md`'s + traceability paragraph. +- **#169's gate implements this ADR**, not 0033's amendment. Its rule page + cites both: 0033 for the record, 0241 for the commit message. +- **The 241 commits on `main` that name a model stay.** Nothing rewrites the + trunk (ADR 0032). +- **Until this ADR is accepted**, `ModelNamedInTheRecordNotTheCommit` is filed + unaccepted in this ADR's set, and a citation of it is `CS0618` (ADR 0066). + +## Checks + +- **Checked against the accepted ADRs.** Touches: + - **0033:** one ruling superseded, as above. Every other ruling stands, + `TraceabilityRecordPerSession` and `ProseNamesNoProduct` included. + - **0032:** the trunk is not rewritten. + - **0066, 0068:** filed unaccepted; the ruling moves under its key. +- **Layer ownership.** None. +- **Analyzer rule.** None here. The gate is #169's, in the commit-message stage + beside `eng/issue-refs.cs` and `eng/dco.cs`. +- **Open questions owned.** None. diff --git a/docs/adr/README.md b/docs/adr/README.md index bbeb91f8..1570386f 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -448,6 +448,14 @@ Filed by the landing session for [#244](https://github.com/Hafeok/Varve/issues/2 |---:|---|---| | [0239](0239-the-maintainers-delegate.md) | The maintainer's delegate: one session on his machine may approve, land and accept for him | Filed unaccepted (#244) | +## Model names in commit messages (#257) + +Filed by the session for [#257](https://github.com/Hafeok/Varve/issues/257), recording the maintainer's ruling of 2026-10-27 for [#169](https://github.com/Hafeok/Varve/issues/169), unaccepted until he accepts it (ADR 0066). Numbered 0241: 0240 is taken on another branch. It supersedes one ruling of 0033. + +| # | Title | Status | +|---:|---|---| +| [0241](0241-model-names-refused-identifiers-allowed.md) | A commit message never names a model; a model's identifier is allowed; supersedes one ruling of 0033 | Filed unaccepted (#257) | + ## Conformance — differential testing against Oxigraph | # | Title | Status | diff --git a/docs/decisions/commit-traceability.md b/docs/decisions/commit-traceability.md index ea411ebb..f11898a4 100644 --- a/docs/decisions/commit-traceability.md +++ b/docs/decisions/commit-traceability.md @@ -35,10 +35,6 @@ decisions: statement: "Prose describes the project as developed with AI assistance under human review and names no product, while records and issues name the tool and model" accepted-by: mailto:emil@okkels-klein.dk accepted-at: 2026-09-22T00:00:00Z - - key: ModelNamedInTheRecordNotTheCommit - statement: "The traceability record names the model by the identifier the session's metadata reports, filled in by the maintainer where the tool will not write it, and a commit message never carries a model's API identifier" - accepted-by: mailto:emil@okkels-klein.dk - accepted-at: 2026-10-02T00:00:00Z - key: AgentsMdHoldsTheRules statement: "The agent rules live in the vendor-neutral AGENTS.md, and CLAUDE.md is one line pointing at it" accepted-by: mailto:emil@okkels-klein.dk @@ -48,6 +44,5 @@ decisions: The rulings of [ADR 0033](../adr/0033-commit-traceability.md) still in force, one line each. The ADR is the narrative; this is what code cites. Acceptance is transcribed from the ADR's Status (ADR 0062). -`ModelNamedInTheRecordNotTheCommit` is the ruling of the amendment of 2026-10-02. It is filed unaccepted, -and its `accepted-at` will be the date the maintainer accepts it, which can be no earlier than the -amendment (ADR 0068). +Moved to a later set: `ModelNamedInTheRecordNotTheCommit`, the ruling of the amendment of 2026-10-02, is +superseded by ADR 0241, which refuses a model's name in a commit message and allows its identifier, in its set. diff --git a/docs/decisions/model-names-refused-identifiers-allowed.md b/docs/decisions/model-names-refused-identifiers-allowed.md new file mode 100644 index 00000000..fd27d7d6 --- /dev/null +++ b/docs/decisions/model-names-refused-identifiers-allowed.md @@ -0,0 +1,13 @@ +--- +set: model-names-refused-identifiers-allowed +namespace: varve +adr: 0241 +decisions: + - key: ModelNamedInTheRecordNotTheCommit + statement: "The traceability record names the model by the identifier the session's metadata reports, filled in by the maintainer where the tool will not write it, and a commit message never carries a model's name, while a model's API identifier and the bare product name are allowed" +--- + +The ruling of [ADR 0241](../adr/0241-model-names-refused-identifiers-allowed.md), +filed unaccepted by the session for #257 (ADR 0066). It supersedes the ruling of +ADR 0033's amendment of 2026-10-02 under the same key, which moved here from +`commit-traceability` (ADR 0068 point 4). From 05d767a41af9c3421a4a921544cf3943a859a91f Mon Sep 17 00:00:00 2001 From: "Claude (Emil)" Date: Tue, 10 Nov 2026 13:29:50 +0000 Subject: [PATCH 2/3] docs(agents): issues are the work log A section after Every commit: work starts from an issue, decisions and blockers go on it when they arise, found work is filed at once, the pull request lists every issue it touches, closings are checked after landing, and abandoned work is closed as not planned. As the prompt's note of 2026-11-10 asks, "the session" in Landing and After landing is whichever session lands: the delegate lands and checks (ADR 0239), and a cloud session posts its head, lists the issues and asks. Refs #257 Co-Authored-By: Claude Signed-off-by: Emil Okkels Klein --- AGENTS.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 659e304c..4150ab65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -165,6 +165,39 @@ model) is allowed, and so is a co-author trailer naming only the product (ADR 0241, superseding ADR 0033's amendment of 2026-10-02). Prose says "developed with AI assistance under human review" and **names no product**. +## Issues are the work log + +The issue, not the session's transcript or close-out, is where anyone looks to +see what is being worked on, what was decided and what is left. + +- **Starting.** Work starts from an issue. The session comments on it when it + starts (branch, and the prompt step it is working from) and posts its plan + there once the plan is agreed. Before opening an issue, search for an open + one that covers the work; a duplicate is closed pointing at the original. +- **While working.** Decisions taken, questions for the maintainer and blockers + go on the issue when they arise, not only in the close-out. The pull request + names its issues as bare #N in prose. +- **Found work is filed when it is found.** A defect, a follow-up or a deferred + part becomes its own issue at once, linked from the issue it came from. A + close-out, a TODO or a commit message is not a place to keep work. +- **Landing.** Before asking for approval, the session lists in the pull + request every issue the change touches: + - each one it resolves fully gets its own `Closes #N` trailer; + - each one it resolves in part gets a comment saying what landed and what is + left, and tracking issues (#15 and the milestone issues) get their boxes + ticked. + + "The session" here and below is whichever session lands. The maintainer's + delegate lands and checks the closings (ADR 0239); a cloud session posts its + head, lists the issues its change touches, and asks. +- **After landing.** The session checks that every issue it meant to close is + closed. If a trailer did not take, it closes the issue by hand with a comment + naming the commit on `main`. +- **Stopping.** Work abandoned or superseded is closed as not planned, with a + comment saying why and what replaces it. +- The traceability record and the close-out link the issues; they do not + replace them. + ## `Varve.Store` behaviour **`docs/spec/log-and-projection-model.md` is the authority** (version 1.8) and From c2e965e3ea354b5cec66a8be62d06e40222d1e70 Mon Sep 17 00:00:00 2001 From: "Claude (Emil)" Date: Tue, 10 Nov 2026 13:34:27 +0000 Subject: [PATCH 3/3] docs(traceability): the record for #257, issues are the work log The prompts, the plan's correction from an amendment to ADR 0241's supersession, what changed and what was found (#258). The model is left for the maintainer to fill in, as ADR 0033 provides. Closes #257 Refs #169 Co-Authored-By: Claude Signed-off-by: Emil Okkels Klein --- ...11-10-issue-257-issues-are-the-work-log.md | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) create mode 100644 docs/traceability/2026-11-10-issue-257-issues-are-the-work-log.md diff --git a/docs/traceability/2026-11-10-issue-257-issues-are-the-work-log.md b/docs/traceability/2026-11-10-issue-257-issues-are-the-work-log.md new file mode 100644 index 00000000..7db0e760 --- /dev/null +++ b/docs/traceability/2026-11-10-issue-257-issues-are-the-work-log.md @@ -0,0 +1,75 @@ +# Issues are the work log, and model names refused in commit messages + +> **Recorded contemporaneously**, by the session that did the work, under +> [ADR 0033](../adr/0033-commit-traceability.md). The prompts are verbatim. The +> transcript itself is held by the maintainer. + +| | | +|---|---| +| **Issues** | [#257](https://github.com/Hafeok/Varve/issues/257); [#169](https://github.com/Hafeok/Varve/issues/169) referenced | +| **Date** | 2026-11-10 | +| **Tool** | Claude Code 2.1.322, a cloud session started from the desktop app. Not the maintainer's delegate (ADR 0239 point 1) | +| **Model** | *Left for the maintainer.* The session's metadata reports the model, but this tool's configuration keeps model identifiers out of every file it pushes, so the maintainer fills it in from the session's metadata (ADR 0033, ADR 0241 point 3). | +| **Session identifier** | `session_01NbWSYQ7rmZCcSgsvBFhZMm` | +| **Branch** | `claude/dazzling-darwin-8irixp`, from `main` at 81fba3d | +| **ADRs** | [0241](../adr/0241-model-names-refused-identifiers-allowed.md) (filed unaccepted), [0033](../adr/0033-commit-traceability.md) (one ruling superseded) | + +## The prompts + +### The session prompt, step 1, as the maintainer attached it + +> ## Step 1 — AGENTS.md: "Issues are the work log" +> +> No issue covers this yet. Search for an open one first; if none exists, open one titled "AGENTS.md: issues are the work log", with the text below as its proposal. That issue is what this step's commit closes. +> +> Add this section to `AGENTS.md` directly after **Every commit**, word for word unless something in it contradicts an accepted ADR, in which case say so on the issue before changing it: +> +> *(the section, as it now stands in `AGENTS.md`, apart from the landing note below)* +> +> Also correct the model-identifier rule. The maintainer's ruling of 2026-10-27, which #169's gate implements, is: **a commit message never carries a model's name; a model's identifier is allowed.** `AGENTS.md` still says the reverse in **Every commit** ("A commit message never carries a model's identifier …") and in **Never** ("… or one whose message carries a model's identifier"). Rewrite both lines to the ruling. The traceability record still names the tool and the model exactly; that line doesn't change. If a PR for #169 is open and touches the same lines, coordinate on #169 instead of conflicting with it, and say which you did. +> +> If `CLAUDE.md` or any other agent instructions file repeats either rule, keep it consistent (CLAUDE.md only points at AGENTS.md today, per ADR 0033). +> +> Commit trailers: `Closes #` and `Refs #169`. +> +> ## Added 2026-11-10 +> +> **AGENTS.md has changed since this prompt was written.** ADR 0239 (the maintainer's delegate) amended the `accepted-by` rule: only the maintainer, or his delegate for a decision he has read, writes `accepted-by`. A cloud session is not the delegate. Fit the new section around that text. In its **Landing** and **After landing** bullets, "the session" means whichever session lands: the delegate lands and checks the closings; a cloud session posts its head, lists the issues its change touches, and asks. + +### The maintainer, in the session + +> Read AGENTS.md, then the session prompt in varve-claude-code-issue-log.md. Note that ADR 0239 has since changed AGENTS.md's accepted-by rule, so fit the new section around it. Add a step 3: #248, the descriptor date set at landing, and where the SBOM creation timestamp comes from. Report your plan for all three steps before writing code. + +> You're right that you are not the delegate: file decisions unaccepted, post your heads, and ask. Post your plan for all three steps on their issues before writing code. + +> All three plans are agreed. Go ahead. […] Step 1's amendment to ADR 0033 and its replacing key stay unaccepted, and the pull request red, until the maintainer or his delegate accepts them. Post each head when its checks other than that are green. + +## The report + +- **No issue covered the work**, so the session opened #257 with the section + as its proposal, commented when it started, and posted the plan there and + on #169. +- **The model rule contradicts an accepted decision.** + `CommitTraceability.ModelNamedInTheRecordNotTheCommit` (ADR 0033's amendment + of 2026-10-02, accepted that day) refused a model's API identifier in a + commit message. The ruling of 2026-10-27 reverses it. ADR 0068 point 2 makes + a change of meaning a supersession, not an amendment, so the plan posted + first (an amendment and a new key) was corrected on #257: **ADR 0241** + supersedes that one ruling, and the key moves to 0241's set unchanged in + name, with the new statement and no `accepted-by` (ADR 0068 point 4). + 0033's Status line names the supersession. 0240 is taken on another branch. +- **What changed:** `AGENTS.md` gains *Issues are the work log* after + **Every commit**, word for word apart from one added paragraph under + **Landing**: "the session" is whichever session lands, as the prompt's note + asks. **Every commit** and **Never** state the ruling. `CONTRIBUTING.md` + repeated the old rule and is rewritten to match. `CLAUDE.md` only points + at `AGENTS.md`, and no other instructions file states either rule. +- **Measured:** `eng/decision-sets.cs` passes with 1,468 decisions, 1,467 + accepted; the one unaccepted is this ADR's. The Release build has zero + warnings. Nothing in code cites the key, so its being unaccepted produces no + `CS0618`; whether the pull request is red on it is for the gates to say. +- **Found:** `eng/decision-report/baseline.md` is stale on `main`. + Regenerating it rewrites some 250 lines this change did not cause. It does + not gate, so it is left for a change of its own: #258. +- **#169 is coordinated, not conflicted with:** no open pull request for it + touched these lines. Its gate, rule page and port remain its own.