From cfbcf168624160a75aa4fe410ec23fccbad99ebc Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Sat, 8 Aug 2026 12:29:49 +0300 Subject: [PATCH 1/4] =?UTF-8?q?feat(standard):=20=C2=A75.7=20Agent=20Conte?= =?UTF-8?q?xt=20Files=20=E2=80=94=20v1.46?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AGENTS.md becomes the single harness-neutral source of truth for agent context; CLAUDE.md is reduced to an @AGENTS.md import plus Claude-only content. Five normative rules: write to AGENTS.md, no duplication, both files tracked, no secrets (with a review gate before un-ignoring a previously private file), and generated blocks targeting AGENTS.md only. This inverts the guidance previously carried only in the spacecraft-agentic-cli skill, which mandated CLAUDE.md as a strict superset — a rule that produced duplication by construction. §16 gains a §5.7 checklist bullet; the Skill Cross-References table gains a spacecraft-agentic-cli row. makeinfo --no-split: zero errors, zero warnings. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 1 + The_Steelbore_Standard.md | 64 +++++++++++++++++++++- The_Steelbore_Standard.texi | 104 ++++++++++++++++++++++++++++++++++-- 3 files changed, 165 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d03287..55dfa15 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,7 @@ Entries are newest-first. Dates are UTC, ISO 8601 (§14). Versioning policy: bum for upstream skill changes, registry updates (§2.1, §15.1), factual corrections to normative content, and brand/identity changes. +- **v1.46 (2026-08-08):** **§5.7 added — Agent Context Files.** §5.2 has enumerated the required root files since the standard's early versions and never named the one file every coding agent actually reads. That silence was not neutral: in its absence each project invented its own arrangement, and a survey of the umbrella found five incompatible conventions running simultaneously across ~39 repositories — byte-identical twins (`sonde`), a symlink (`achernar`), a declared superset (`copy/cpx`, `pearlite`), a thin pointer in one direction (`flux`, `tachyon`, `os-prober`), and genuinely divergent files each holding facts the other lacked (`anvil`, `bravais`, `gitway`, `loran`, `zamak`). The failure mode is specific and silent. `AGENTS.md` is the cross-vendor convention (Codex CLI, Cursor, Aider, OpenCode, Goose); Claude Code reads `CLAUDE.md`. When both exist as parallel prose they are edited in different sessions and drift, and **the agent reading the stale copy is never told it is stale** — it proceeds confidently on a build command that changed six weeks ago. Several files had already noticed and responded with the wrong remedy, carrying explicit "whenever you update CLAUDE.md, update AGENTS.md in the same pass" instructions: a maintenance tax paid manually, forever, that the drift proves was not being paid. §5.7 makes **`AGENTS.md` the single authority** — required at every project root alongside the §5.2 files, harness-neutral, carrying build/test/lint commands, architectural invariants, forbidden patterns, layout, and every fact an agent cannot infer from the code. `CLAUDE.md`, where a project ships one, becomes an **`@AGENTS.md` import plus only what is meaningless to a non-Claude harness** — Skill-tool invocations, `.claude/` paths, slash commands, Claude-client MCP configuration — and MUST NOT restate, summarize, or mirror it. Five rules attach. **Write to `AGENTS.md`**: new project knowledge goes there by default, and "update the context file" always means `AGENTS.md`; this is the rule that keeps the overlay from re-growing into a second copy one session at a time. **No duplication**, with the corollary that a "keep these in sync" instruction is evidence the split is wrong and MUST be removed rather than honored. **Both tracked** — a `.gitignore` entry for either breaks the `@AGENTS.md` import on a fresh clone and hides project knowledge from every contributor who did not author it; 15 of the surveyed repositories were ignoring one or both. **No secrets**, which is the clause that makes the tracking rule safe rather than merely tidy: context files become published artifacts, so credentials, tokens, keys, private hostnames or network topology, and personal filesystem paths are out, and a file that was previously ignored MUST be reviewed for sensitive content *before* it is un-ignored — a file that was safe as a local scratchpad has not thereby been cleared for publication, and un-ignoring is effectively irreversible once pushed. **Generated blocks target `AGENTS.md` only**: tooling that renders managed regions into context files — rule synchronizers, task systems — reintroduces exactly the duplication the import removes if it writes both, so the obligation is placed on the tooling rather than left for a human to notice. Other harness files (`GEMINI.md`, `.cursorrules`) follow the `CLAUDE.md` pattern rather than earning clauses of their own. This section **inverts the guidance previously carried only in the `spacecraft-agentic-cli` skill**, which instructed authors to make `CLAUDE.md` a strict superset of `AGENTS.md` and to start by symlinking or copying it — a rule that produced the duplication by construction and that every new scaffold reproduced. That skill's `references/agents-md-authoring.md` and both `assets/` templates are rewritten to match, and the Skill Cross-References table gains a `spacecraft-agentic-cli` row for context-file authoring, which had never appeared there despite the skill being the implementation layer for it. §16 gains a §5.7 checklist bullet. Nothing in §5.2 changes: `AGENTS.md` is added to the required set, and no existing required file is relaxed or removed. - **v1.45 (2026-08-06):** **§11.6 added — System Theme Declaration & Resolution.** §11 has been a palette *family* since v1.35 and §11.1 has required every palette reference to go through a named theme since v1.34, yet nothing in the document said what an application does when the *machine* has an opinion. The gap was invisible from both ends: §11.1 answers "how do I reference a color", §11.4 answers "which palette is mine", and neither question is "which member of the family renders on this system, right now" — so an application could satisfy every clause in §11 while shipping exactly one hard-wired theme, deaf to the desktop it runs on. Steelbore OS has meanwhile had a theme declaration for months — Bravais's `theme.nix` is a single word that re-themes every terminal, both bars, the TTY and greetd from one slug — which made the omission look like it did not exist. It ends at a rebuild: that machinery resolves at build time and exports per-role hex but never the slug, so a *running* application can see individual colors and still not learn which theme is active, nor whether high contrast or mono is in force. §11.6 closes it from both sides. **Applications register the family, not a theme.** §11.6.1 separates two obligations §11.4 had conflated: a project *authors* against one palette and *registers* thirteen — the six conforming palettes (`steelbore`, `steelbore-blue`, `steelbore-blackpinkpanther`, `steelbore-matrixgreen`, `steelbore-navywhite`, `tokyonight`), each with its `-high-contrast` sibling, plus `steelbore-mono`. Three were already required by §11.4 and §11.1.1, so the section adds ten, all of them already written out in `steelbore.toml`; every one binds the same eleven role tokens, so a theme layer that reads that file registers them in a loop. `steelbore-classic` is deliberately **not** in the mandatory set: it keeps the legacy six-role contract (§11.2), defines no surface class, and carries an `info` token that is not one of §11.1's eleven roles at all, so it is registrable only by an application that implements that contract too. **Resolution is two-stage, and that is the load-bearing decision.** Stage 1 picks a base palette from five sources — in-app selection, `SPACECRAFT_THEME`, the system declaration, the platform's light/dark preference, then the project's §11.4 default. Stage 2 picks a *variant of that palette* — a pinned `-high-contrast`/`-mono` slug, then `NO_COLOR` ⇒ `steelbore-mono`, then §18.1 accessible mode, then the platform's high-contrast preference under the §18.3 precedent that a system-wide preference has already been expressed. Keeping the stages apart is what makes the section composable: an accessibility signal chooses a *sibling*, never a palette, so it can never silently change the brand — exactly the promise §11.1.1 has made since v1.33. §18.1's four-source precedence is consumed, not restated and not modified; there is still one switch. An unknown or unregistered slug **falls through to the next source and is never fatal**, so a typo in `/etc` cannot leave a machine without a working interface (§3.1, graceful degradation), and the resolved theme plus the source that decided it are reported under `--verbose`, as §18.1 already requires of accessible mode. **Light and dark needed §11.4 read precisely.** `steelbore-navywhite` is the family's only light-canvas member, so a platform light preference cannot be answered by lifting a token — only by rendering a different palette. §11.6.2 states plainly that §11.4 forbids *combining* tokens from two palettes and that a color-scheme switch combines nothing: the entire token set is replaced at once, the new canvas comes with it unaltered, and no frame ever carries a token from two palettes. **Switching is compliant; mixing remains forbidden** — with two hard rules attached, that the switch is atomic and whole-surface (an application that cannot re-theme atomically resolves once at startup and holds), and that the canvas travels with the palette. The family pair is `steelbore` ⇄ `steelbore-navywhite`; a project may declare its own, or declare `light = none` with a stated reason on the §14.2.1 documented-exception footing, which buys it nothing under §18. Solarized Dark and Light are a natural pair upstream and §11.5 bars both from adoption, so neither may ever be the target of the color-scheme source. **The declaration is a file, deliberately.** `/etc/steelbore/theme.toml`, overridden per user by `$XDG_CONFIG_HOME/steelbore/theme.toml`, carrying `active` (required), an optional `light`/`dark` pair, `follow-color-scheme`, and `high-contrast`. A file, not a bus: the contract has to work for a CLI in a text console, where there is no session bus, no portal, and no portable way to ask the terminal what color its background is — which is why the platform color-scheme source is graphical-only and why the file is the channel that reaches everything else. Absence of the file is *no declaration*; a file saying `active = "steelbore"` is a declaration *of Modern*, and the distinction matters because a system may need to pin Modern rather than inherit whatever the default later becomes. **The declaration carries slugs and never colors** — the same division §13 draws for component systems, where the platform chooses the widget vocabulary and never supplies the palette; an OS-installed theme registry is advisory and the application's own `steelbore.toml` governs, so per-role color environment variables are explicitly *not* a Standard interface. The variable is **`SPACECRAFT_THEME`**, in the umbrella-wide `SPACECRAFT_` namespace §18.1 established with `SPACECRAFT_A11Y`; `STEELBORE_THEME` is named as **not** a Standard interface, because it is already in use as a boolean shell flag and giving it slug semantics would make `STEELBORE_THEME=true` resolve to a theme that does not exist and fall through in silence. **§11.6.5** puts the symmetrical obligation on Steelbore OS in every flavor: render the declaration from its own selection rather than maintain it by hand, export the slug so it reaches graphical sessions and system services rather than login shells alone, keep the platform's color-scheme preference in agreement with the declared palette's polarity, and validate the slug at evaluation time so an unknown theme fails the build rather than the boot. **Scope is both namespaces §6.4 authorizes** — `Spacecraft-Software` and `UnbreakableMJ` — and all three interface classes: a CLI is not exempt, because it already honors `NO_COLOR` and already emits ANSI, so it already has a theme whether or not it names one. Libraries and anything with no user-facing output record §11.6 as N/A. Registered games are **not** exempt: §18.5 carves out §18 and §10, never §11, and a game satisfies this section in its menus, HUD, and settings chrome, not in the world it simulates. Three things are unchanged. **`steelbore` is still the sole default** — §11.6 changes what an application *can* render, never what it renders when nothing is declared, which remains the project's §11.4 palette and Modern where none is declared. **§11.4's mixing prohibition is unchanged**, and is now stated precisely enough to be enforceable. **§18 is unchanged** — §11.6 reads its resolved state and adds no accessibility rule of its own; a declaration file's `high-contrast` key selects a theme sibling and is explicitly barred from being read as enabling accessible mode. §11.4 gains two bullets and three amended ones; §16 gains a §11.6 bullet rather than lengthening the §11 one; the Skill Cross-References table gains a `steelbore-color-palette` row, closing a smaller gap found in the same pass — the skill has been the normatively cited canonical source in §11.4 since v1.39 and had never appeared in the table that tells a reader which skill to load. Recorded as a factual correction in the same entry: the §11 chapter-head palette-family table listed six slugs where `[meta] palette-family` in `steelbore.toml` and §11.4.1 both list seven — **`tokyonight` was missing** from the one table a reader consults first, present everywhere else since v1.39. It is added, and the table gains a canvas-polarity column, which §11.6.2 now makes normative content rather than an observation. - **v1.44 (2026-08-05):** **Skill Cross-References corrected — the accessibility row named a skill that does not exist.** The table pointed at `spacecraft-accessibility`; the skill has been `spacecraft-accessibility-support` since it was added. An agent following the Standard to find the §18 implementation layer would have looked for a directory that is not there, and the failure mode is silent — a missing skill does not announce itself, it simply never loads, so §18 work would proceed without the reference the Standard directs it to. The row now names the skill correctly. Nothing else in the table changed, and every other skill name it cites was verified against the catalogue in the same pass. The drift was pure naming: `spacecraft-standard-constitution`'s own cross-reference table has carried the correct name throughout, so the two documents disagreed and the published one was wrong — a reminder that a cross-reference is normative content like any other clause, and that renaming a skill is a two-repo edit. This entry records a factual correction only; no rule changes, and no section text was touched. - **v1.43 (2026-08-05):** **§3.2.1 published — Platform-Specific Compiler & Linker Flag Caveats.** This section has existed in the `spacecraft-standard-constitution` skill for some time and was **never in the published document**: no version carried it, and neither changelog recorded it. It entered the skill during a rename commit rather than a normative one, so the usual bump-and-record step was skipped and the omission was invisible from either side — the skill looked complete, and the Standard had nothing to be missing. It surfaced only when the `.texi` and the skill were compared section by section. This entry closes that gap; there is **no new rule here**, only a rule that agents have been following from the skill finally appearing in the document that is supposed to be normative. The section states that compiler and linker optimization flags are **not universally portable** across operating systems and distributions — just as systemd-specific settings do not apply to non-systemd distros (GNU Guix System, Void Linux, Gentoo with OpenRC), linker and LTO flags must be adapted to the target platform's toolchain layout. The concrete case is **NixOS / Steelbore OS Bravais**: because NixOS isolates packages in `/nix/store`, GCC's LTO plugin is not on the standard linker search path, so `-flto` **must** be paired with `-fuse-ld=mold` (preferred) or `-fuse-ld=bfd` (fallback) or the build fails to link. The governing rule generalizes it: whenever recommending or applying `-flto`, `-march=native`, or PGO, verify whether the target OS needs supplementary flags or a different linker, and document the OS-specific requirement alongside the flag. This is the platform-specific companion to §3.2's existing requirement that every applied *and* every disabled flag be explicitly noted — §3.2 says record the flag state, §3.2.1 says the correct state is not the same everywhere. §16 needs no new bullet: its §3.2 item already requires flags to be "applied/disabled with explicit notation," which is precisely what §3.2.1 makes platform-aware. diff --git a/The_Steelbore_Standard.md b/The_Steelbore_Standard.md index 0fe6832..0e14668 100644 --- a/The_Steelbore_Standard.md +++ b/The_Steelbore_Standard.md @@ -29,7 +29,7 @@ repository](https://github.com/Spacecraft-Software/Standard), newest entry first. It is kept out of this document so the standard reads as the rules *in force* rather than the record of how they got there. -This document is **version 1.45**, updated 2026-08-06 (§14: UTC, ISO +This document is **version 1.46**, updated 2026-08-08 (§14: UTC, ISO 8601). The skill encoding of the standard keeps a parallel history in `spacecraft-standard-constitution/references/CHANGELOG.md` in the [Construct @@ -577,6 +577,60 @@ packing**, not after a failure. | Machine-enforced | The cap MUST be checked by an automated gate that runs both in the skill repository’s CI on every pull request and push to the default branch, and in whatever command produces the distributable bundle. A developer-installed git hook is a convenience, never the gate — hooks are opt-in per clone and cannot be relied on. | | Over-limit skills do not ship | A skill whose description exceeds the cap MUST NOT be packed, committed, or published. Trim the description; do not raise the cap. | +## §5.7 — Agent Context Files + +Coding agents load a project’s root context file into their window at +the start of every session. Different harnesses read different filenames +— `AGENTS.md` is the cross-vendor convention (Codex CLI, Cursor, Aider, +OpenCode, Goose, Gemini CLI), while Claude Code reads `CLAUDE.md`. +Maintaining both as parallel prose guarantees drift: the two copies are +edited in different sessions, diverge, and the agent that reads the +stale one is misinformed. This section fixes a single source of truth. + +**`AGENTS.md` is the authority.** Every project **must** ship an +`AGENTS.md` at its root, in addition to the §5.2 posture files. It is +harness-neutral: it carries the project’s build, test, and lint +commands, architectural invariants, forbidden patterns, repository +layout, and any fact an agent cannot infer from the code itself. + +**`CLAUDE.md` is a thin overlay, and is also required.** Claude Code +reads `CLAUDE.md` and does *not* read `AGENTS.md`, so a project shipping +only an `AGENTS.md` gives a Claude session no project context at all. +The file **must** consist of an `@AGENTS.md` import followed only by +content that is meaningless to a non-Claude harness — Skill-tool +invocations, `.claude/` paths, Claude Code slash commands, and +Claude-client MCP configuration. It **must not** restate, summarize, or +mirror `AGENTS.md`. Where there is nothing Claude-only to say, the +import and its note are the whole file: + + # CLAUDE.md + + @AGENTS.md + + > Record project knowledge in `AGENTS.md`, not here. This file holds + > only Claude-Code-only context. + +**Mandatory rules:** + +| Rule | Detail | +|----|----| +| Write to `AGENTS.md` | New project knowledge — a build command, an invariant, a gotcha — MUST be written to `AGENTS.md`. An agent or maintainer adds to `CLAUDE.md` only when the fact is meaningless to a harness that is not Claude Code. "Update the context file" always means `AGENTS.md`. | +| No duplication | A rule stated in `AGENTS.md` MUST NOT be restated in `CLAUDE.md`. Instructions of the form "keep these two files in sync" are evidence the split is wrong and MUST be removed rather than honored. | +| Both tracked | Both files are version-controlled artifacts, not agent-local scratch, and both are required. A `.gitignore` entry for either one breaks the `@AGENTS.md` import on a fresh clone and hides project knowledge from every contributor who did not author it. | +| No secrets | Because they are tracked and published, context files are subject to the same hygiene as any other repository file: no credentials, tokens, keys, private hostnames or network topology, or personal filesystem paths. A context file that was previously ignored MUST be reviewed for sensitive content **before** it is un-ignored. | +| Generated blocks | Tooling that renders managed regions into context files (rule synchronizers, task systems) MUST target `AGENTS.md` only. Writing the same block into both files reintroduces the duplication the import exists to remove. | + +A relative import resolves against the file containing it, never against +the working directory, so each project’s `CLAUDE.md` reaches its own +`AGENTS.md`. Claude Code walks up the directory tree and concatenates +every `CLAUDE.md` it finds, so a project nested under another inherits +the ancestor’s context in addition to its own — which is why an ancestor +file must not restate what a child already says. + +Other harness-specific files (`GEMINI.md`, `.cursorrules`, and similar) +follow the `CLAUDE.md` pattern: import or reference `AGENTS.md`, then +add only what is specific to that harness. + ———————————————————————— # §6 — Platform & Systems Requirements @@ -2337,6 +2391,13 @@ Before finalising **any** Spacecraft Software artifact, mentally verify: command that produces the bundle, not only by a local git hook — N/A for projects that ship no skills +- [ ] **§5.7** Agent context files: `AGENTS.md` and `CLAUDE.md` both + present at the repository root and version-controlled; `CLAUDE.md` is + an `@AGENTS.md` import plus Claude-only content and restates nothing; + neither file is gitignored; no credentials, private hostnames, or + personal filesystem paths in either; managed blocks rendered into + `AGENTS.md` only + - [ ] **§6.1** POSIX-compliant CLI/system tools - [ ] **§7** Shell scripts are POSIX-compatible; Nushell/Ion native @@ -2446,6 +2507,7 @@ skipping it. | Creating IDE / terminal themes | `spacecraft-theme-factory` | | Resolving or declaring the system theme (§11.6) | `steelbore-color-palette` | | Implementing or auditing accessibility (§18) | `spacecraft-accessibility-support` | +| Authoring `AGENTS.md` / `CLAUDE.md` (§5.7) | `spacecraft-agentic-cli` | | All other Spacecraft Software work | `spacecraft-standard-constitution` | # Concept Index diff --git a/The_Steelbore_Standard.texi b/The_Steelbore_Standard.texi index a4d143c..30b6bce 100644 --- a/The_Steelbore_Standard.texi +++ b/The_Steelbore_Standard.texi @@ -5,11 +5,11 @@ @setfilename The_Steelbore_Standard.info @documentencoding UTF-8 @documentlanguage en -@settitle The Steelbore Standard 1.45 +@settitle The Steelbore Standard 1.46 @c %**end of header -@set VERSION 1.45 -@set UPDATED 2026-08-06 +@set VERSION 1.46 +@set UPDATED 2026-08-08 @set SUBDOMAIN https://Standard.SpacecraftSoftware.org/ @copying @@ -753,6 +753,7 @@ do; posture says what they should @emph{expect} from the maintainer. * Maintainer Discretion:: * Package Distribution:: * Skill Packaging:: +* Agent Context Files:: @end menu @node Default Posture @@ -958,6 +959,92 @@ Over-limit skills do not ship committed, or published. Trim the description; do not raise the cap. @end multitable +@node Agent Context Files +@section §5.7 — Agent Context Files + +Coding agents load a project's root context file into their window at the +start of every session. Different harnesses read different filenames --- +@code{AGENTS.md} is the cross-vendor convention (Codex CLI, Cursor, Aider, +OpenCode, Goose, Gemini CLI), while Claude Code reads @code{CLAUDE.md}. +Maintaining both as parallel prose guarantees drift: the two copies are +edited in different sessions, diverge, and the agent that reads the stale +one is misinformed. This section fixes a single source of truth. + +@strong{@code{AGENTS.md} is the authority.} Every project @strong{must} +ship an @code{AGENTS.md} at its root, in addition to the §5.2 posture +files. It is harness-neutral: it carries the project's build, test, and +lint commands, architectural invariants, forbidden patterns, repository +layout, and any fact an agent cannot infer from the code itself. + +@strong{@code{CLAUDE.md} is a thin overlay, and is also required.} Claude +Code reads @code{CLAUDE.md} and does @emph{not} read @code{AGENTS.md}, so a +project shipping only an @code{AGENTS.md} gives a Claude session no project +context at all. The file @strong{must} consist of an @code{@@AGENTS.md} +import followed only by content that is meaningless to a non-Claude harness +--- Skill-tool invocations, @code{.claude/} paths, Claude Code slash +commands, and Claude-client MCP configuration. It @strong{must not} +restate, summarize, or mirror @code{AGENTS.md}. Where there is nothing +Claude-only to say, the import and its note are the whole file: + +@example +# CLAUDE.md + +@@AGENTS.md + +> Record project knowledge in `AGENTS.md`, not here. This file holds +> only Claude-Code-only context. +@end example + +@strong{Mandatory rules:} + +@multitable {No secrets} {New project knowledge --- a build command, an invariant, a gotcha --- MUST be written to @code{AGENTS.md}. An agent or maintainer adds to @code{CLAUDE.md} only when the fact is meaningless to a harness that is not Claude Code. "Update the context file" always means @code{AGENTS.md}.} +@headitem +Rule + @tab Detail +@item +Write to @code{AGENTS.md} + @tab New project knowledge --- a build command, an invariant, a gotcha +--- MUST be written to @code{AGENTS.md}. An agent or maintainer adds to +@code{CLAUDE.md} only when the fact is meaningless to a harness that is +not Claude Code. "Update the context file" always means +@code{AGENTS.md}. +@item +No duplication + @tab A rule stated in @code{AGENTS.md} MUST NOT be restated in +@code{CLAUDE.md}. Instructions of the form "keep these two files in sync" +are evidence the split is wrong and MUST be removed rather than honored. +@item +Both tracked + @tab Both files are version-controlled artifacts, not agent-local +scratch, and both are required. A @code{.gitignore} entry for either one +breaks the @code{@@AGENTS.md} import on a fresh clone and hides project +knowledge from every contributor who did not author it. +@item +No secrets + @tab Because they are tracked and published, context files are subject +to the same hygiene as any other repository file: no credentials, +tokens, keys, private hostnames or network topology, or personal +filesystem paths. A context file that was previously ignored MUST be +reviewed for sensitive content @strong{before} it is un-ignored. +@item +Generated blocks + @tab Tooling that renders managed regions into context files (rule +synchronizers, task systems) MUST target @code{AGENTS.md} only. Writing +the same block into both files reintroduces the duplication the import +exists to remove. +@end multitable + +A relative import resolves against the file containing it, never against +the working directory, so each project's @code{CLAUDE.md} reaches its own +@code{AGENTS.md}. Claude Code walks up the directory tree and concatenates +every @code{CLAUDE.md} it finds, so a project nested under another +inherits the ancestor's context in addition to its own --- which is why an +ancestor file must not restate what a child already says. + +Other harness-specific files (@code{GEMINI.md}, @code{.cursorrules}, and +similar) follow the @code{CLAUDE.md} pattern: import or reference +@code{AGENTS.md}, then add only what is specific to that harness. + @iftex @bigskip@hrule@bigskip @end iftex @@ -4076,6 +4163,14 @@ sees them, not as raw lines); the cap is enforced by CI @emph{and} by the command that produces the bundle, not only by a local git hook --- N/A for projects that ship no skills @item +☐ @strong{§5.7} Agent context files: @code{AGENTS.md} and +@code{CLAUDE.md} both present at the repository root and +version-controlled; @code{CLAUDE.md} is an @code{@@AGENTS.md} import plus +Claude-only content and restates nothing; +neither file is gitignored; no credentials, private hostnames, or personal +filesystem paths in either; managed blocks rendered into @code{AGENTS.md} +only +@item ☐ @strong{§6.1} POSIX-compliant CLI/system tools @item ☐ @strong{§7} Shell scripts are POSIX-compatible; Nushell/Ion native @@ -4214,6 +4309,9 @@ Resolving or declaring the system theme (§11.6) Implementing or auditing accessibility (§18) @tab @code{spacecraft-accessibility-support} @item +Authoring @code{AGENTS.md} / @code{CLAUDE.md} (§5.7) + @tab @code{spacecraft-agentic-cli} +@item All other Spacecraft Software work @tab @code{spacecraft-standard-constitution} @end multitable From 9b474cc2ed91f592fd069f83dcb266a3f7d0d778 Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Sat, 8 Aug 2026 13:09:57 +0300 Subject: [PATCH 2/4] =?UTF-8?q?docs:=20adopt=20the=20=C2=A75.7=20AGENTS.md?= =?UTF-8?q?-first=20context-file=20layout?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md becomes AGENTS.md (the authoritative, harness-neutral file) and a new CLAUDE.md carries the @AGENTS.md import plus Claude-only notes. Both leave .gitignore and become tracked, per the §5.7 rule this repo just published — the standard governs itself (§8 self-applies). The Files table row is updated from "Gitignored / local agent guidance" to two tracked rows. Reviewed for sensitive content before un-ignoring: no credentials, hostnames, or personal filesystem paths. Co-Authored-By: Claude Opus 5 (1M context) --- .gitignore | 2 - AGENTS.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 6 +++ 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index f65dfa5..3c8086c 100644 --- a/.gitignore +++ b/.gitignore @@ -28,8 +28,6 @@ The_Steelbore_Standard.odt chat/ # Agent-local guidance and exports (not for publication) -CLAUDE.md -AGENTS.md GEMINI.md CODEX.md .claude/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..33737a6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,111 @@ +# AGENTS.md + +## What this repo is + +A single-document publication repo for **The Steelbore Standard** — the engineering specification governing every project under Spacecraft Software (Zamak, Bravais, Ferrocast, Craton, Ironway, Caliper, Mawaqit, etc.). + +There is no application source code. The artifact is the standard itself, authored in GNU Texinfo. + +The umbrella was renamed from `Steelbore` to `Spacecraft Software` in v1.7 (2026-05-15). The filesystem rename has landed — canonical paths live under `/spacecraft-software/`, and `/steelbore/` survives only as a compatibility symlink farm. Always use the `/spacecraft-software/` paths in new artifacts; treat any lingering `/steelbore/` reference as legacy. The OS line (`Steelbore OS`, `Steelbore OS Bravais`, `Steelbore OS Lattice`) retains the Steelbore name and is unaffected. + +## Source-of-truth flow + +``` +/spacecraft-software/construct/spacecraft-standard-constitution/SKILL.md (upstream — the canonical skill) + │ + ▼ manual sync when the skill changes +/spacecraft-software/standard/The_Steelbore_Standard.texi (tracked — Texinfo source of truth) + │ + ├──▶ make info → The_Steelbore_Standard.info (gitignored) + ├──▶ make html → The_Steelbore_Standard.html (gitignored, served at Standard.SpacecraftSoftware.org) + ├──▶ make md → The_Steelbore_Standard.md (tracked — GitHub-rendered companion) + ├──▶ make pdf → The_Steelbore_Standard.pdf (gitignored) + └──▶ make docx → The_Steelbore_Standard.docx (gitignored, on request only) +``` + +The `.texi` is the sole source of truth. The `.md` is a generated GFM companion kept tracked for GitHub rendering — regenerate it with `make md` after any `.texi` edit. `.html`, `.info`, `.pdf`, and `.docx`/`.odt` are gitignored derived outputs. + +**Do not edit `.md` directly** — changes will be overwritten by the next `make md`. + +## Regenerating outputs + +The `Makefile` is the canonical recipe — **but `make` is not on PATH in this environment.** Only the underlying tools are installed (`makeinfo`, `texi2any`, `texi2pdf`, `pandoc`, `reuse`, under `/run/current-system/sw/bin`). Run the raw commands directly (they are exactly what the Makefile targets shell out to), or provision make ephemerally (`guix shell gnumake` / `nix shell nixpkgs#gnumake`). Keep the raw commands here in sync with the `Makefile`. + +| Output | `make` target | Raw command (what actually works today) | +|--------|---------------|------------------------------------------| +| `.info` | `make info` | `makeinfo --no-split The_Steelbore_Standard.texi` | +| `.html` | `make html` | `texi2any --html --no-split --css-include=spacecraft.css The_Steelbore_Standard.texi` | +| `.md` | `make md` | `texi2any --docbook The_Steelbore_Standard.texi -o /tmp/std.xml && pandoc -f docbook -t gfm /tmp/std.xml -o The_Steelbore_Standard.md` | +| `.pdf` | `make pdf` | `texi2pdf --texinfo=@afourpaper The_Steelbore_Standard.texi` | +| `.docx` | `make docx` | `texi2any --docbook … && pandoc -f docbook -t docx …` (on request only) | + +**Why `.md` routes through DocBook:** pandoc 3.7 dropped the Texinfo *reader*, so `pandoc -f texinfo` fails with "Unknown input format texinfo". The `texi2any --docbook → pandoc -f docbook` path is the supported route — do not "simplify" it back to a direct texinfo read. + +Verification after any regeneration: +- `makeinfo --no-split The_Steelbore_Standard.texi` → **zero errors, zero warnings**. This is the *only* build check — CI does not compile the `.texi` (see CI below), so a malformed source still passes CI. Always run this locally before pushing. +- `grep "@set VERSION" The_Steelbore_Standard.texi` → matches the intended version (also confirm `@settitle` and `@set UPDATED`). +- HTML build renders with the Void Navy background via `spacecraft.css`. + +## CI — what gates a PR + +`.github/workflows/ci.yml` runs on every PR and every push to `main`: + +1. **`reuse lint`** — REUSE/SPDX compliance must pass. The `.texi` and `.md` carry *example* SPDX tags in §4.3, so `REUSE.toml` overrides them to a real license. If `reuse lint` fails right after a content edit, check that override first. +2. **`python3 .github/validate-configs.py`** — walks the tree and parses every `.json` / `.jsonc` / `.toml` / `.yaml` / `.yml`, exiting non-zero on any malformed config. New files are picked up automatically (no list to maintain). + +There is **no document-build step in CI** — keep the local `makeinfo` check as your gate for `.texi` correctness. + +## External sources to sync against + +- `/spacecraft-software/construct/spacecraft-standard-constitution/SKILL.md` — the skill encoding of the Standard. Nominally upstream (skill → `.texi`), but in practice normative changes are often authored in the `.texi` here first and then back-synced to the skill. Either way both must end up consistent at the same version. A sync touches the SKILL.md masthead, the frontmatter `description`, the relevant section body, **and `references/CHANGELOG.md`** in the Construct repo. +- `/spacecraft-software/projects/PROJECTS.md` — hand-maintained tracker of every Spacecraft Software project. Drives **§2.1 codename registry** updates (new entries, status corrections like `Active`/`Reserved`/`Completed`/`Planning`/`Pending rename`) and **§15.1 subdomain table** updates (new project URLs). When the user asks to sync the "registry" or "project statuses," this is the source to compare against. + +## Versioning policy + +Bump the **three** version-bearing header lines in the `.texi` — `@settitle The Steelbore Standard `, `@set VERSION `, and `@set UPDATED ` (it is easy to miss `@settitle`) — and prepend a newest-first entry to **`CHANGELOG.md`** at the repo root (the history left the document in v1.37; §1 — Preamble now only points at the file) for: + +- **Upstream skill changes** — new sections, new normative rules in `SKILL.md` +- **Registry updates** — additions or status corrections to §2.1 or §15.1 driven by `PROJECTS.md` +- **Factual corrections** — any change that alters normative content readers rely on +- **Brand / identity changes** — umbrella renames, domain changes, contact-email changes + +After bumping, regenerate the `.md` companion (the `make md` raw command above) and commit `.texi`, `.md`, and `CHANGELOG.md` in the same commit. Then sync the Construct repo in its own PR — `SKILL.md` (masthead, frontmatter `description`, section body) and `references/CHANGELOG.md` — keeping the version and date identical across both repos. + +The skill's own metadata may lag; the published standard's version history is the user-facing record. Minor same-day corrections (e.g., a URL fix) can share the same version if they haven't been published yet, but increment once published. Same-day bumps with different content still increment (e.g. v1.30 and v1.31 both dated 2026-06-24). + +## Change workflow (both repos) + +- **Branch + PR, never push to `main`.** Every change — even a one-line version bump — goes through a feature branch → PR → squash-merge → delete branch, in both the Standard and Construct repos. Use signed commits (§6.3); rebases/amends must preserve signatures. +- **A normative change is a two-repo, two-PR job.** The rule lives in `The_Steelbore_Standard.texi` (here) *and* in `spacecraft-standard-constitution/SKILL.md` + `references/CHANGELOG.md` (Construct). Land them as separate PRs — typically Standard first, Construct second — at the same version. + +## Self-applies + +The standard governs itself. Most-pertinent rules for work in this repo: + +- **§6.3 — Signed & Verified Commits.** Every commit MUST be cryptographically signed and show "Verified" on GitHub. This is non-negotiable, applies to programmatic/assistant-driven commits too, and rewrites (rebase/amend/cherry-pick) must preserve signatures. +- **§8 — Documentation (Texinfo).** This repo IS the §8-compliant Texinfo manual for The Steelbore Standard: `.texi` source with `info`/`html`/`md`/`pdf`/`docx` Makefile targets. It is *published* as HTML at `Standard.SpacecraftSoftware.org` rather than shipped as an installed Info package, so the `Makefile` has no `install-info` target (unlike a packaged library manual would). +- **§14 — UTC + ISO 8601** for any timestamp anywhere in the document (changelog entries, `@set UPDATED` date). +- **§15.3 — Third-Party Attribution.** A `CREDITS.md` is required at root if external work is substantially built upon. Currently none — this is original work. + +## Files + +| Path | Status | Purpose | +|------|--------|---------| +| `The_Steelbore_Standard.texi` | Tracked | **Source of truth** — the standard in Texinfo | +| `The_Steelbore_Standard.md` | Tracked | Generated GFM companion (from `make md`) — for GitHub rendering | +| `CHANGELOG.md` | Tracked | **Hand-maintained** version history of the standard (extracted from §1 in v1.37). Not generated — do not overwrite it from the `.texi` | +| `LICENSE` | Tracked | Symlink → `LICENSES/CC-BY-SA-4.0.txt` (§4.3: GitHub license detection + REUSE, one source of truth) | +| `spacecraft.css` | Tracked | Spacecraft HTML theme for `texi2any --html` output | +| `Makefile` | Tracked | Build targets: `info`, `html`, `md`, `pdf`, `docx`, `clean` | +| `The_Steelbore_Standard.info` | Gitignored | Generated — Info reader format | +| `The_Steelbore_Standard.html` | Gitignored | Generated — website output | +| `The_Steelbore_Standard.pdf` | Gitignored | Generated — printable reference | +| `The_Steelbore_Standard.docx` | Gitignored | Generated on request (`make docx`) | +| `The_Steelbore_Standard.odt` | Gitignored | Not produced by default pipeline | +| `REUSE.toml` | Tracked | REUSE override for files containing example SPDX headers (`.texi`, `.md`, dotfiles, `.github/**`) | +| `LICENSES/` | Tracked | REUSE license texts — `CC-BY-SA-4.0.txt` (document) and `GPL-3.0-or-later.txt` (tooling) | +| `.github/workflows/ci.yml` | Tracked | CI: `reuse lint` + config validation on every PR and push to `main` | +| `.github/validate-configs.py` | Tracked | Config parser invoked by CI — JSON/JSONC/TOML/YAML, auto-discovers files | +| `.gitignore` | Tracked | Excludes generated outputs, TeX aux files, agent-local files | +| `AGENTS.md` | Tracked | **This file** — authoritative agent guidance (§5.7) | +| `CLAUDE.md` | Tracked | `@AGENTS.md` import plus Claude-Code-only context (§5.7) | diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2e3a3b9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,6 @@ +# CLAUDE.md + +@AGENTS.md + +> Record project knowledge in `AGENTS.md`, not here. This file holds only +> Claude-Code-only context (Standard §5.7). From 0a1f4b3bfc1db26e3225e513660d8fea25917ade Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Sat, 8 Aug 2026 13:15:13 +0300 Subject: [PATCH 3/4] fix(reuse): cover the now-tracked AGENTS.md and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §5.7 makes both files tracked artifacts, so reuse lint began failing on them. They carry no inline SPDX tags by design — CLAUDE.md's first non-heading line must be the bare @AGENTS.md import. A REUSE.toml override is the right instrument, matching how the .texi and .md are already handled. Co-Authored-By: Claude Opus 5 (1M context) --- REUSE.toml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/REUSE.toml b/REUSE.toml index bcf72b2..0b58ca4 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -8,6 +8,15 @@ precedence = "override" SPDX-FileCopyrightText = "2026 Mohamed Hammad " SPDX-License-Identifier = "CC-BY-SA-4.0" +# Agent context files (§5.7). Tracked artifacts, so they need REUSE coverage; they +# carry no inline SPDX tags because CLAUDE.md's first non-heading line must be the +# bare `@AGENTS.md` import. Document-class → CC-BY-SA-4.0. +[[annotations]] +path = ["AGENTS.md", "CLAUDE.md"] +precedence = "override" +SPDX-FileCopyrightText = "2026 Mohamed Hammad " +SPDX-License-Identifier = "CC-BY-SA-4.0" + # CI tooling is software-class (§4.1.1) → GPL-3.0-or-later, even though the Standard # document itself is CC-BY-SA-4.0. [[annotations]] From a8b80db2f2367af73916fd48a6cf59d71a87ad19 Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Sat, 8 Aug 2026 13:16:05 +0300 Subject: [PATCH 4/4] fix(reuse): SPDX headers on the now-tracked AGENTS.md and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §5.7 makes both files tracked artifacts, so reuse lint began failing on them. Inline headers rather than a REUSE.toml override: the .texi/.md overrides exist because those files contain *example* SPDX tags in §4.3 that must not be parsed as real ones, which is not true here. A leading HTML comment also costs nothing in context — Claude Code strips block-level comments before injecting a CLAUDE.md — and the @AGENTS.md import only needs to be on its own line, not the first one. Co-Authored-By: Claude Opus 5 (1M context) --- AGENTS.md | 5 +++++ CLAUDE.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 33737a6..9056482 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,8 @@ + + # AGENTS.md ## What this repo is diff --git a/CLAUDE.md b/CLAUDE.md index 2e3a3b9..7b27e7c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,8 @@ + + # CLAUDE.md @AGENTS.md