From ee6679a25da434b42a3ab752c5288b9b73f1cff6 Mon Sep 17 00:00:00 2001 From: UnbreakableMJ Date: Wed, 5 Aug 2026 09:17:59 +0000 Subject: [PATCH] =?UTF-8?q?feat(standard):=20publish=20=C2=A73.2.1=20Platf?= =?UTF-8?q?orm-Specific=20Compiler=20&=20Linker=20Flag=20Caveats=20?= =?UTF-8?q?=E2=80=94=20v1.43?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comparing the .texi against the skill section by section turned up exactly one structural difference: §3.2.1 exists in spacecraft-standard-constitution and has never existed 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 bump-and-record step was skipped. The omission was invisible from both sides — the skill looked complete, and the Standard had nothing to be missing. There is no new rule here. Agents have been following §3.2.1 out of the skill; this puts it in the document that is supposed to be normative. The section: compiler and linker optimization flags are not universally portable across operating systems and distributions, so linker and LTO flags must be adapted to the target platform's toolchain layout. Concretely, NixOS isolates packages in /nix/store and GCC's LTO plugin is therefore off the standard linker search path, so -flto must be paired with -fuse-ld=mold (preferred) or -fuse-ld=bfd or the build fails to link. Generalized: verify whether the target OS needs supplementary flags or a different linker whenever applying -flto, -march=native, or PGO, and document that alongside the flag. This is the platform-specific companion to §3.2's existing rule that every applied and every disabled flag be noted — §3.2 says record the flag state, §3.2.1 says the correct state is not the same everywhere. §16 gains no bullet: its §3.2 item already requires flags to be "applied/disabled with explicit notation", which §3.2.1 simply makes platform-aware. @settitle, @set VERSION, @set UPDATED bumped to 1.43 / 2026-08-05. Added as a @subsection with its own @menu under §3.2, mirroring how §3.1.1 sits under §3.1; subsections stay out of the master menu, as they already do there. makeinfo --no-split: zero errors, zero warnings. reuse lint and validate-configs pass. .md companion regenerated via texi2any --docbook | pandoc -f docbook -t gfm. Co-Authored-By: Claude Opus 5 (1M context) --- CHANGELOG.md | 1 + The_Steelbore_Standard.md | 22 +++++++++++++++++++++- The_Steelbore_Standard.texi | 31 +++++++++++++++++++++++++++++-- 3 files changed, 51 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d14b9f6..58b5d19 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.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. - **v1.42 (2026-08-05):** **§13 corrected — a component system per platform, not one for every platform.** §13 required **Material Design** as "the required component system for all graphical applications," a rule written when the graphical surface in scope was Flutter and web. It has been unsatisfiable for native desktop since the day it was written: **GTK 4** ships Adwaita and the GNOME HIG, **Qt 6** ships Fusion and the KDE HIG, and neither has a Material component set to theme — so a GTK or Qt application could not pass the §16 audit gate no matter how it was built, and the only honest options were a permanent filed deviation or an application that matches neither its own toolkit nor Material. Worse, imposing a foreign component system on a native toolkit fights exactly the platform integration §18 depends on: the accessibility bridge, the window manager, the system high-contrast and reduced-motion preferences, and the settings portal are all wired to the toolkit's own vocabulary. §13 is accordingly rewritten around the requirement that actually carries the intent — **every graphical application declares exactly one component system, in its `README.md` beside the §5.2 posture section, and follows it consistently** — with the system determined by the platform rather than by preference: **Material Design** for Flutter, web, mobile, and cross-platform GUI, and for custom-drawn or immediate-mode UI that declares no platform HIG; **GNOME HIG** via libadwaita for GTK 4; **KDE HIG** via Qt Quick Controls or Fusion for Qt 6. Material Design remains the default wherever the platform supplies no system of its own, so nothing that was compliant under v1.41 becomes non-compliant here — the clause is narrowed, never widened. Three things are explicitly unchanged: **§11 binding is unconditional** — whichever system is declared, every palette reference still goes through the named `steelbore` theme (§11.1), because a component system chooses the widget vocabulary and never supplies the colors; **WCAG 2.2 Level AA** remains the contrast floor with the measured pairing stated; and **§18 still governs wherever the two overlap**. The §16 checklist bullet is rewritten from "Material Design UI/UX" to the declare-and-follow form naming all three systems, and the Skill Cross-References table gains `spacecraft-gtk-guidelines` and `spacecraft-qt-guidelines` rows — the two skills that implement this section for the native-desktop toolkits. Both are Rust-first under §3.1 (`gtk-rs` for GTK, CXX-Qt for Qt), so choosing a native desktop toolkit does not become a route around the memory-safe-language preference. - **v1.41 (2026-08-04):** **§3.1.1 added — TypeScript over JavaScript.** §3.1 named Rust as the preferred language and prescribed ASLR+CFI where Rust is not viable, but it had nothing to say about the one runtime where that framing does not apply: JavaScript is already memory-safe, so the memory-safety lever is inert, and the section fell silent exactly where a stability rule was still needed. §3.1.1 supplies it — **type safety is the Priority 1 lever on this runtime**. Where a memory-safe alternative exists (Rust to WebAssembly, Rust or Go on a server, Flutter/Dart for a UI) §3.1 still chooses it; where the JavaScript runtime is genuinely required — a browser page, a Node/Deno/Bun program, an Electron app, an npm-distributed tool, a VS Code extension — the **source language MUST be TypeScript**, and plain JavaScript source becomes a documented exemption rather than a default. Six requirements attach: `"strict": true` plus `noUncheckedIndexedAccess`, `noImplicitOverride`, and `exactOptionalPropertyTypes` (relaxing `strict` is a Priority 1 regression); no `any` and no non-null `!` in production paths (use `unknown` and narrow); `@ts-ignore` prohibited outright in favor of `@ts-expect-error` with a stated reason, which fails the build once the suppression stops being needed; **run-time validation at every trust boundary**, since a type annotation is a compile-time claim and asserting an unverified shape is the silent-failure mode §3.1 already forbids; **`tsc --noEmit` gating CI**, because esbuild, SWC, and Bun strip types without checking them, and a project that only transpiles has not satisfied this section; and loading `spacecraft-typescript-guidelines` before writing or reviewing TypeScript. Emitted `.js` and source maps in a build directory are derived artifacts and out of scope — the rule governs what is authored and committed. Three narrow cases need no filing: a tool's own configuration file that must be `.js` (e.g. `eslint.config.js` where no TypeScript loader exists), a vendored or upstream-derived file carried under §4.2, and generated output. Everything else — including "it is only a small script" — requires a documented technical exemption, on the same footing as the §3.1 memory-safe-language exemption. §16 gains a checklist bullet; the skill cross-reference table gains a TypeScript row. - **v1.40 (2026-07-27):** **Two gaps closed: where work may be sent, and what must be measured before a skill is packed.** **§6.4 added — Authorized Contribution Targets (Non-Negotiable).** §6.3 has always said how a commit must be signed on "a Spacecraft Software-controlled Git remote" without ever defining that set, so nothing in the standard stopped a script, a CI job, or an assistant-driven session from pushing a branch or opening a pull request against a third-party repository. §6.4 names the authorized namespaces — `github.com/Spacecraft-Software` and `github.com/UnbreakableMJ`, with a future Spacecraft Software-controlled host (Gitway) inheriting the same standing — and makes every other destination **outbound** and **default-deny**: silence is a denial, not permission. **Automation never initiates** an outbound contribution, and authorization for one does not carry to the next task, session, or repository; only Mohamed Hammad, acting explicitly and per contribution, may authorize one (§5.4). The rule is not git-only — publishing to a package registry under a namespace Spacecraft Software does not control (`crates.io`, npm, PyPI, AUR, Nixpkgs, Guix, Flathub) and filing issues or patches on an external tracker or mailing list are outbound under the same rule. **Forks stay free**: a fork under an authorized namespace may be created and pushed to at will, because that is our namespace — turning a fork branch into an upstream PR is the gated act. Where an upstream change is needed, §4.2's carry-the-patch-in-tree route is preferred to upstreaming. The free-software/GNU posture (§1) yields the identity clauses (§2, §11–§12, §15) but **not** this one: sending anything to GNU, the FSF, or Savannah still needs explicit authorization. An unauthorized submission MUST be withdrawn as soon as it is discovered, and recorded. **§5.6 added — Skill Packaging Requirements.** Skills are software-class artifacts (§4.1.1) whose loader limits are only discovered at install time, after the packing work is done: a `SKILL.md` frontmatter `description` over **1024** characters is rejected on load. §5.6 caps it at **1000 rendered characters** — a deliberate 24-character margin — and pins down *rendered*: a YAML folded scalar (`description: >`) joins its wrapped lines with single spaces and keeps a trailing newline, so raw line lengths are not the measurement, and block (`>`/`|`) and single-line plain or quoted forms alike are counted after folding. The cap MUST be **machine-enforced** in two places — the skill repository's CI on every pull request and push to the default branch, *and* the command that produces the distributable bundle. A developer-installed git hook is a convenience, never the gate: hooks are opt-in per clone. An over-limit skill MUST NOT be packed, committed, or published; trim the description rather than raise the cap. §16 gains a checklist bullet for each section. diff --git a/The_Steelbore_Standard.md b/The_Steelbore_Standard.md index 9d53e96..266dc06 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.42**, updated 2026-08-05 (§14: UTC, ISO +This document is **version 1.43**, updated 2026-08-05 (§14: UTC, ISO 8601). The skill encoding of the standard keeps a parallel history in `spacecraft-standard-constitution/references/CHANGELOG.md` in the [Construct @@ -270,6 +270,26 @@ documented. regressions must be documented and justified — and it is the evidence by which the concurrency-vs-serial trade-off above is decided. +### §3.2.1 — Platform-Specific Compiler & Linker Flag Caveats + +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 (e.g., GNU Guix System, +Void Linux, Gentoo with OpenRC), linker and LTO flags must be adapted to +the target platform’s toolchain layout. + +**NixOS / Steelbore OS Bravais:** Because NixOS isolates packages in the +`/nix/store`, GCC’s LTO plugin is not on the standard linker search +path. When using `-flto` (Link Time Optimization) on NixOS, you **must** +explicitly point GCC’s linker to the GCC LTO plugin via `-fuse-ld=mold` +(preferred) or `-fuse-ld=bfd` (fallback). Without this, LTO-enabled +builds will fail to link. + +> **Rule:** Whenever recommending or applying compiler/linker flags — +> especially `-flto`, `-march=native`, or PGO — verify whether the +> target OS requires supplementary flags or alternative linker +> selection. Document the OS-specific requirements alongside the flags. + ## §3.3 — Priority 3: Security by Design - Kernel hardening (XanMod, grsecurity profiles) where applicable. diff --git a/The_Steelbore_Standard.texi b/The_Steelbore_Standard.texi index d1585fc..f5dfa06 100644 --- a/The_Steelbore_Standard.texi +++ b/The_Steelbore_Standard.texi @@ -5,10 +5,10 @@ @setfilename The_Steelbore_Standard.info @documentencoding UTF-8 @documentlanguage en -@settitle The Steelbore Standard 1.42 +@settitle The Steelbore Standard 1.43 @c %**end of header -@set VERSION 1.42 +@set VERSION 1.43 @set UPDATED 2026-08-05 @set SUBDOMAIN https://Standard.SpacecraftSoftware.org/ @@ -483,6 +483,33 @@ work; regressions must be documented and justified --- and it is the evidence by which the concurrency-vs-serial trade-off above is decided. @end itemize +@menu +* Platform Flag Caveats:: +@end menu + +@node Platform Flag Caveats +@subsection §3.2.1 — Platform-Specific Compiler & Linker Flag Caveats + +Compiler and linker optimization flags are @strong{not universally +portable} across operating systems and distributions. Just as +systemd-specific settings do not apply to non-systemd distros (e.g., GNU +Guix System, Void Linux, Gentoo with OpenRC), linker and LTO flags must +be adapted to the target platform's toolchain layout. + +@strong{NixOS / Steelbore OS Bravais:} Because NixOS isolates packages in +the @file{/nix/store}, GCC's LTO plugin is not on the standard linker +search path. When using @code{-flto} (Link Time Optimization) on NixOS, +you @strong{must} explicitly point GCC's linker to the GCC LTO plugin via +@code{-fuse-ld=mold} (preferred) or @code{-fuse-ld=bfd} (fallback). +Without this, LTO-enabled builds will fail to link. + +@quotation +@strong{Rule:} Whenever recommending or applying compiler/linker flags --- +especially @code{-flto}, @code{-march=native}, or PGO --- verify whether +the target OS requires supplementary flags or alternative linker +selection. Document the OS-specific requirements alongside the flags. +@end quotation + @node Priority 3 @section §3.3 — Priority 3: Security by Design @itemize