From 7d1d1aa3864d6fc0749059c02a82de4be2a5c8ce Mon Sep 17 00:00:00 2001 From: Julian Noble Date: Tue, 7 Jul 2026 13:32:32 +1000 Subject: [PATCH] commit conventions VCS-neutral; template DOX/goals ownership design input Root AGENTS.md "Git Commit Conventions" renamed "Commit Conventions (any VCS)": the Co-Authored-By/AI-attribution ban and the Assisted-by trailer apply to git commits and fossil checkins alike (git parses trailers structurally, fossil comments are free text - either way the trailer is the last line of the message). Generated projects start fossil-only but may adopt git; punkshell itself is git-primary today and could flip. CLAUDE.md mirror section updated to match. G-027 detail: documentation/goals ownership design input - layout-owned child AGENTS.md docs ride the pull channel under the unmodified-since-install classification; project-owned skeletons (thin root AGENTS.md, GOALS.md, goals/AGENTS.md, empty GOALS-archive.md) are seeded once and never pulled; commit conventions are part of the seed (developer-changeable, VCS-neutral); layout-owned marker convention; transitive chains inherit the parent''s modified docs as their baseline. G-012 detail: AGENTS.md template payloads recorded as the same hazard class as live .gitignore payloads - a template AGENTS.md under src/project_layouts/ is binding DOX for agents walking the punkshell tree though written for generated projects; needs the same inert storage + materialize-at-generation treatment. First field test: the tomlish project was seeded today with the thin root AGENTS.md + CLAUDE.md + GOALS framework this design describes. Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com --- AGENTS.md | 6 ++-- CLAUDE.md | 8 ++--- goals/G-012-template-payload-safety.md | 8 +++++ goals/G-027-derived-project-pull-updates.md | 37 +++++++++++++++++++++ 4 files changed, 53 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index da276fb8..cecb106b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,10 +87,12 @@ When the user requests a durable behavior change, record it here or in the relev - If the active editor is on a source-derived snapshot, bootstrap copy, or build output path such as `src/bootsupport/`, root `modules/`, root `lib/`, `modules_tcl8/`, `modules_tcl9/`, `lib_tcl8/`, or `lib_tcl9/`, confirm the intended target before editing unless the user explicitly named that path. - Do not commit new executable binaries (shared libs, .exe, native .so/.dll/.dylib, bare ELF/Mach-O, or zip-based .tm modules embedding executables) to the repository. Existing binaries in `bin/`, `src/vfs/`, `src/vendorlib/`, `src/vendormodules/`, and `src/bootsupport/` are there intentionally pending the build/retrieval infrastructure tracked by goals G-004/G-005/G-006; do not flag, "fix", or hassle the developer about these — they are known and will be removed once G-005 (zig build) or G-006 (pre-built download) provides an alternative. This rule stops agents from adding new binaries; it does not block the developer's interim commits of existing vendor/vfs binaries. -## Git Commit Conventions +## Commit Conventions (any VCS) + +These conventions apply to every VCS commit an agent makes - git commits and fossil checkins alike. Projects generated from punkshell layouts start fossil-only but may adopt git (punkshell itself is currently git-primary); the conventions are VCS-neutral by design and are seeded into generated projects, where the project developer may change them. - Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages. -- When an agent constructs and executes the `git commit` command itself (staging, composing the message, and committing), it must append one `Assisted-by` trailer as the last line of the commit body. If the user commits manually, no trailer is required. +- When an agent constructs and executes the commit command itself (`git commit`, `fossil commit` - staging, composing the message, and committing), it must append one `Assisted-by` trailer as the last line of the commit message. If the user commits manually, no trailer is required. (git parses trailers structurally; fossil checkin comments are free text - in both cases the convention is simply the last line of the message.) - Trailer format (single line, semicolon-separated key=value): `Assisted-by: harness=; primary-model=; api-location=` Examples: diff --git a/CLAUDE.md b/CLAUDE.md index d5f150a6..7e8e4304 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,8 +6,8 @@ Before working, read and follow the root `AGENTS.md`, then read and follow any n If this file conflicts with `AGENTS.md`, `AGENTS.md` wins. -## Git Commit Conventions +## Commit Conventions (any VCS) -- Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages. -- When an agent constructs and executes the `git commit` command itself (staging, composing the message, and committing), it must append one `Assisted-by` trailer as the last line of the commit body. If the user commits manually, no trailer is required. -- Trailer format and field derivation rules live in the root `AGENTS.md` "Git Commit Conventions" section. `AGENTS.md` is the source of truth; this section is a reminder that the policy applies to Claude harnesses too. +- Never add "Co-Authored-By" lines or any AI-attribution footers to commit messages - git commits and fossil checkins alike. +- When an agent constructs and executes the commit command itself (`git commit`, `fossil commit` - staging, composing the message, and committing), it must append one `Assisted-by` trailer as the last line of the commit message. If the user commits manually, no trailer is required. +- Trailer format and field derivation rules live in the root `AGENTS.md` "Commit Conventions (any VCS)" section. `AGENTS.md` is the source of truth; this section is a reminder that the policy applies to Claude harnesses too. diff --git a/goals/G-012-template-payload-safety.md b/goals/G-012-template-payload-safety.md index 2c32064b..a512c613 100644 --- a/goals/G-012-template-payload-safety.md +++ b/goals/G-012-template-payload-safety.md @@ -72,6 +72,14 @@ payload drift is unmanaged. The same inert-payload treatment should apply to any future live-config payloads in layouts (e.g. `.gitattributes`); `.fossil-settings/` payloads in layouts are inert by nature (fossil reads them only at a checkout root) and need no change. +- **AGENTS.md payloads are the same hazard class** (identified 2026-07-07 while designing + template DOX for derived projects, see G-027 detail): an `AGENTS.md` stored as template + payload under `src/project_layouts/` is live DOX for any agent whose work touches layout + paths in the punkshell repo itself - the DOX walking rule makes it binding contract, though + its instructions are written for a *generated* project (e.g. its build/test commands would + operate on template internals). When layouts gain AGENTS.md payloads (per the G-027 + documentation-ownership design), they need the same inert storage + materialize-at-generation + treatment as the .gitignore payloads. - fauxlink background: target encoded in the filename (`+` for `/`, url-style escapes), no filesystem support required, application-driven resolution - see `src/bootsupport/modules/fauxlink-0.1.1.tm` doctools header. diff --git a/goals/G-027-derived-project-pull-updates.md b/goals/G-027-derived-project-pull-updates.md index 3c611514..01af5fdd 100644 --- a/goals/G-027-derived-project-pull-updates.md +++ b/goals/G-027-derived-project-pull-updates.md @@ -61,6 +61,43 @@ work from a stale project, or delivered as its first step). consent-gating principle of G-006. May be recorded as deferred with rationale. +## Documentation and goals ownership (design input, 2026-07-07) + +What a pull may touch splits by ownership, not by file type: + +- **Layout-owned docs**: most of the DOX tree documents the layout machinery + itself (src/AGENTS.md build workflow, src/bootsupport/AGENTS.md contracts, + src/tests/AGENTS.md harness usage, src/modules/AGENTS.md authoring + conventions). Documentation whose subject is pulled infrastructure has the + same provenance as that infrastructure and rides the same update channel - + ordinary payload files under the target-side classification above + (punkcheck-unmodified -> update; locally modified -> leave and report, + optionally delivering the new version aside or as a diff for hand-merging). + The tomlish src/tests port demonstrated the premise: punkshell's + src/tests/AGENTS.md applied nearly verbatim to the derived project. +- **Project-owned skeletons**: the root AGENTS.md (project identity, repo-wide + notes, preferences, child index) and the GOALS framework (GOALS.md, + goals/AGENTS.md, and an empty GOALS-archive.md so the maintenance rules' + archive reference resolves from day one) are installed once at generation as + thin skeletons and never pulled. Keeping the root template thin - rails, + index, purpose placeholder - minimises the file agents customise most, and + with it the diverged-so-frozen surface. +- **Commit conventions are part of the seed**: the VCS-neutral commit + conventions (Co-Authored-By/AI-attribution ban + Assisted-by trailer; see + root AGENTS.md "Commit Conventions (any VCS)") propagate into the generated + root AGENTS.md as seeded defaults the subproject developer may change. + Generated projects start fossil-only but may adopt git, so the seeded text + must stay VCS-neutral. +- **Divergence-reducing convention**: layout-owned docs carry a marker line + ("layout-owned; updated by pull when unmodified - record project-specific + rules in the nearest project-owned doc instead") so DOX's + update-the-closest-doc habit doesn't silently accrete project content into + pull-managed files. +- **Transitive chains**: since pulls come from the parent project (not the + root punkshell), an intermediate project's deliberate modifications to + layout-owned docs become the baseline its own derived projects inherit - + a feature, not a conflict. + ## Alternatives considered - Keeping push-only and just fixing its path robustness - rejected as the end