From 90346a3570bd24ab7163d5b5b0af43b91910d5b9 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 24 Jul 2026 15:44:38 -0700 Subject: [PATCH 1/2] Add verbatim Durable Knowledge and Self-Improvement section The rule that durable guidance belongs in the committed docs, not agent memory, lived only in the preamble - a non-verbatim zone that never carries - so downstream repos lacked it and an agent wrote a fleet rule to its local memory instead of AGENTS.md. Promote it to a verbatim section so it carries to every repo, and broaden it to the full self- improvement duty: record durable lessons in the governance docs as part of the change, propose upstream where the doc is carried, fold good patterns in and design bad ones out. Remove the superseded preamble line and declare the section in files.json and section-model.md in the same change, per the add-a-section rule. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 7 +++++-- spec/files.json | 2 +- spec/section-model.md | 1 + 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d1d37f84..af577511 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,8 +4,6 @@ Treat this file as authoritative for everything else; don't restate its rules elsewhere. A project's **project-specific conventions and public-API/behavioral contracts** (e.g. a "Library API Conventions" section) live in that project's own `AGENTS.md`, **not** in [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) - that file targets GitHub Copilot / VS Code specifically, while this file is the agent-agnostic one every coding agent is directed to read, so any rule a reviewer must honor has to live here to be provider-independent. -**Durable guidance lives in committed docs, not agent memory.** Agent memory does not persist across machines or environments; anything a future agent must honor belongs in a committed file - working rules here in `AGENTS.md`, the running backlog in [`README.md`](./README.md)'s TODO section, code style in `CODESTYLE.md`. Do not rely on a memory that a later session on another host will not have. - ## Foundational Principles The specific rules in this file implement a few governing principles. Read these first: they are the reason the branching, release, and versioning rules are shaped the way they are, and every rule below serves one of them. @@ -15,6 +13,11 @@ The specific rules in this file implement a few governing principles. Read these - **Two version numbers, two jobs.** The 2-digit `major.minor` in `version.json` carries human meaning - the maintainer raises it only for a functional change (feature, behavior or API change, breaking change), at their discretion - while NBGV owns the patch position and always increments with git height, so every build is uniquely versioned with no edit. Human-facing docs name the 2-digit line; the toolchain guarantees monotonic builds. See "Release Model". - **Contracts state what, not how, and favor reuse.** [`WORKFLOW.md`](./WORKFLOW.md) fixes required outcomes, not a required implementation - two repos may satisfy a guarantee with different YAML. Within that freedom, apply good engineering practice: minimize duplication and maximize reuse, which is why the pipeline splits a carried, generic orchestration layer from a repo-owned build layer. +## Durable Knowledge and Self-Improvement + +- **Durable knowledge lives in the committed docs, not in agent memory.** Anything a future agent must honor - a rule, a contract, a hard-won gotcha, a pattern worth repeating or one to avoid - belongs in a committed governance file (`AGENTS.md`, `CODESTYLE.md`, `WORKFLOW.md`, or the repo's tracked backlog). Agent memory does not survive a new session, a new machine, or a new environment, so it holds only environment-specific nuance and in-flight session state - never anything whose loss on reset would matter. A durable lesson left only in memory is lost to the next agent. +- **Keep the governance current as you work.** When work surfaces something durable - a rule worth enforcing, a recurring gotcha, a positive pattern to repeat, a negative one to design out - record it in the governance docs as part of that change, rather than leaving it in a local note or routing around it with a one-off workaround. Where the governing doc is carried from a template this repo cannot edit directly, propose the change upstream instead of only fixing it locally. Governance is not static: it improves by agents folding good patterns in and designing bad ones out. + ## Repository Boundaries and Write Safety A state-changing GitHub call is the highest-blast-radius thing an agent does here: it runs under the maintainer's identity, so one wrong target writes to another owner's repository as the maintainer - an outward-facing, hard-to-reverse act. These rules bound every write - a git push, an API mutation, a comment, a label, a merge - on any platform. Reads are unrestricted. The bounds below are on writes. diff --git a/spec/files.json b/spec/files.json index 577a2091..5825c32c 100644 --- a/spec/files.json +++ b/spec/files.json @@ -2,7 +2,7 @@ "$schema": "./files.schema.json", "note": "The standardization baseline: files and sections a fleet repo is expected to carry, and their intent authority. The audit mechanically checks presence (letter). Equivalence (intent) is judged by hand, and a section for an absent language or target is N/A. Each entry, and each section, carries an appliesTo selector - see spec/scope-model.md for the scope model and selector vocabulary. Each entry also has a fidelity (presence by default, or intent, verbatim, interface) governing how faithfully the content is checked - see spec/fidelity-model.md. The per-section fidelity of AGENTS.md, which sections are verbatim fleet-law and which are repo-specific, is defined in spec/section-model.md.", "baseline": [ - { "path": "AGENTS.md", "fidelity": "intent", "sections": [{ "name": "Foundational Principles", "fidelity": "verbatim" }, { "name": "Repository Boundaries and Write Safety", "fidelity": "verbatim" }, { "name": "Git and Commit Rules", "fidelity": "verbatim" }, { "name": "Branching Model", "fidelity": "verbatim" }, { "name": "Release Model", "fidelity": "verbatim" }, { "name": "Operational Repositories", "fidelity": "verbatim" }, { "name": "Pull Request Title and Commit Message Conventions", "fidelity": "verbatim" }, { "name": "Documentation Style Conventions", "fidelity": "verbatim" }, { "name": "Verification Discipline", "fidelity": "verbatim" }, { "name": "PR Review Etiquette", "fidelity": "verbatim" }, { "name": "Communicating with the User", "fidelity": "verbatim" }, { "name": "Workflow YAML Conventions", "fidelity": "verbatim" }, { "name": "Supported Development Platforms", "fidelity": "verbatim" }, { "name": "Devcontainer", "fidelity": "intent" }, { "name": "Editor and Tasks", "fidelity": "verbatim" }, { "name": "Repository Details", "fidelity": "verbatim" }, { "name": "Repository Layout", "fidelity": "intent" }], "intentRef": "AGENTS.md", "appliesTo": "*" }, + { "path": "AGENTS.md", "fidelity": "intent", "sections": [{ "name": "Foundational Principles", "fidelity": "verbatim" }, { "name": "Durable Knowledge and Self-Improvement", "fidelity": "verbatim" }, { "name": "Repository Boundaries and Write Safety", "fidelity": "verbatim" }, { "name": "Git and Commit Rules", "fidelity": "verbatim" }, { "name": "Branching Model", "fidelity": "verbatim" }, { "name": "Release Model", "fidelity": "verbatim" }, { "name": "Operational Repositories", "fidelity": "verbatim" }, { "name": "Pull Request Title and Commit Message Conventions", "fidelity": "verbatim" }, { "name": "Documentation Style Conventions", "fidelity": "verbatim" }, { "name": "Verification Discipline", "fidelity": "verbatim" }, { "name": "PR Review Etiquette", "fidelity": "verbatim" }, { "name": "Communicating with the User", "fidelity": "verbatim" }, { "name": "Workflow YAML Conventions", "fidelity": "verbatim" }, { "name": "Supported Development Platforms", "fidelity": "verbatim" }, { "name": "Devcontainer", "fidelity": "intent" }, { "name": "Editor and Tasks", "fidelity": "verbatim" }, { "name": "Repository Details", "fidelity": "verbatim" }, { "name": "Repository Layout", "fidelity": "intent" }], "intentRef": "AGENTS.md", "appliesTo": "*" }, { "path": "CODESTYLE.md", "fidelity": "intent", "whole": true, "placeholders": ["InternalsVisibleTo project names"], "intentRef": "CODESTYLE.md", "appliesTo": "*" }, { "path": "WORKFLOW.md", "fidelity": "intent", "whole": true, "intentRef": "WORKFLOW.md", "appliesTo": "*" }, { "path": "README.md", "appliesTo": "*" }, diff --git a/spec/section-model.md b/spec/section-model.md index 28282184..ee0abe53 100644 --- a/spec/section-model.md +++ b/spec/section-model.md @@ -22,6 +22,7 @@ A section is one of the following. Fidelity is declared in [files.json][files], | Section | Fidelity | Reason | | --- | --- | --- | | Foundational Principles | verbatim | the governing rationale, universal | +| Durable Knowledge and Self-Improvement | verbatim | universal meta-rule: durable knowledge belongs in the committed docs and agents keep them current | | Repository Boundaries and Write Safety | verbatim | universal write-safety law | | Git and Commit Rules | verbatim | universal git law | | Branching Model | verbatim | universal (repo-specific history SHAs removed so it can carry) | From 74018ebeba50b400d9ef547b172a973f1deb5352 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 24 Jul 2026 15:48:08 -0700 Subject: [PATCH 2/2] Scope the durable-knowledge backlog to a committed one "The repo's tracked backlog" read as ambiguous against the section's own committed-not-memory thrust - GitHub Issues are tracked but not committed. Name a committed backlog (a README.md TODO section) so the example cannot be read as an uncommitted tracker. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index af577511..2a556820 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ The specific rules in this file implement a few governing principles. Read these ## Durable Knowledge and Self-Improvement -- **Durable knowledge lives in the committed docs, not in agent memory.** Anything a future agent must honor - a rule, a contract, a hard-won gotcha, a pattern worth repeating or one to avoid - belongs in a committed governance file (`AGENTS.md`, `CODESTYLE.md`, `WORKFLOW.md`, or the repo's tracked backlog). Agent memory does not survive a new session, a new machine, or a new environment, so it holds only environment-specific nuance and in-flight session state - never anything whose loss on reset would matter. A durable lesson left only in memory is lost to the next agent. +- **Durable knowledge lives in the committed docs, not in agent memory.** Anything a future agent must honor - a rule, a contract, a hard-won gotcha, a pattern worth repeating or one to avoid - belongs in a committed governance file (`AGENTS.md`, `CODESTYLE.md`, `WORKFLOW.md`, or a committed backlog such as a `README.md` TODO section). Agent memory does not survive a new session, a new machine, or a new environment, so it holds only environment-specific nuance and in-flight session state - never anything whose loss on reset would matter. A durable lesson left only in memory is lost to the next agent. - **Keep the governance current as you work.** When work surfaces something durable - a rule worth enforcing, a recurring gotcha, a positive pattern to repeat, a negative one to design out - record it in the governance docs as part of that change, rather than leaving it in a local note or routing around it with a one-off workaround. Where the governing doc is carried from a template this repo cannot edit directly, propose the change upstream instead of only fixing it locally. Governance is not static: it improves by agents folding good patterns in and designing bad ones out. ## Repository Boundaries and Write Safety