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