Skip to content

feat(spacecraft-standard): sync skill to v1.22 — §7 Shell Environment #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
UnbreakableMJ merged 2 commits into from
Jun 18, 2026
Merged

feat(spacecraft-standard): sync skill to v1.22 — §7 Shell Environment #3

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8d0bef
feat(spacecraft-standard): sync skill to v1.22 — add §7 Shell Environ…
UnbreakableMJ Jun 18, 2026
e813123
docs(spacecraft-standard): sync §14.2 email obfuscation note (v1.22)
UnbreakableMJ Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 72 additions & 49 deletions spacecraft-standard/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,23 @@ description: >
Spacecraft Software-umbrella project — even if the user doesn't explicitly mention the Standard.
If the user mentions "Spacecraft Software", a Spacecraft Software subproject name, or asks you to work on
anything in the Spacecraft Software ecosystem, consult this skill immediately. It encodes
The Steelbore Standard v1.21 so you never need to ask for it or have it attached to a
prompt again.
The Steelbore Standard v1.22 (§7 Shell Environment; §14.2 email obfuscation note) so
you never need to ask for it or have it attached to a prompt again.
license: GPL-3.0-or-later
maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
website: https://Construct.SpacecraftSoftware.org/
---

# The Steelbore Standard — Compliance Reference

**Version:** 1.21 | **Date:** 2026-06-17 | **Author:** Mohamed Hammad
**Version:** 1.22 | **Date:** 2026-06-18 | **Author:** Mohamed Hammad
**Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
**Copyright:** Copyright (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)

This skill encodes The Steelbore Standard in full. Apply every applicable section
to any artifact you produce under the standard. The 13-point compliance checklist
in §14 is your audit gate — run through it mentally before finalising any output.
to any artifact you produce under the standard. The 14-point compliance checklist
in §15 is your audit gate — run through it mentally before finalising any output.

> **License note:** This skill is `GPL-3.0-or-later` (skills are software-class, §4.1.1).
> The *published* Standard document it encodes is licensed `CC-BY-SA-4.0`.
Expand Down Expand Up @@ -109,7 +109,7 @@ back-rename.

Existing legacy-named projects MAY be renamed under the v1.2 convention at the
maintainer's discretion — renames are optional. When a rename happens, update
this table and §13.1's subdomain table in the same commit.
this table and §14.1's subdomain table in the same commit.

### §2.2 — Skill IDs are functional, not codenamed

Expand Down Expand Up @@ -239,7 +239,7 @@ upstream's license in full — independent of the project's own GPL/AGPL choice:
- **Ship** each distinct upstream license text in the project's `LICENSES/` directory (§4.3).
- **Verify compatibility** of the upstream license with the project's GPL/AGPL license
before inclusion.
- This is the legal/mechanical obligation; §13.3's `CREDITS.md` is the human-readable
- This is the legal/mechanical obligation; §14.3's `CREDITS.md` is the human-readable
narrative counterpart. When both are triggered, both apply.

### §4.3 — SPDX & REUSE Compliance
Expand Down Expand Up @@ -322,7 +322,7 @@ A project may declare itself **intended for general use**. When it does:
semantic versioning, maintained `CHANGELOG.md`, deprecation policy, and a
documented support window for the current major version.

**General-use registry** (keep in sync with §13.1 subdomain table):
**General-use registry** (keep in sync with §14.1 subdomain table):

| Project | Posture |
|--------------|---------------|
Expand Down Expand Up @@ -395,7 +395,22 @@ keys, Spacecraft Software commits migrate accordingly.

---

## §7 — Privacy-Friendly Application (PFA) Policy
## §7 — Shell Environment

Spacecraft Software tooling, documentation, and CI pipelines target **four first-class shell environments**: **Nushell**, **Ion**, **Brush**, and **Bash**. All four are equally supported; none is deprecated or downgraded.

### §7.1 — Script Portability Policy

| Rule | Detail |
|------|--------|
| Default: POSIX-compatible | Shell scripts in source trees, CI pipelines, `Makefile` targets, and documentation examples **must** be written to the POSIX sh subset unless a shell-native feature is required. POSIX scripts run correctly in Bash and Brush without modification. |
| Nushell / Ion native variants when needed | When a task cannot be expressed cleanly in POSIX sh (structured data pipelines, typed parameters, Nushell modules), provide a Nushell (`.nu`) and/or Ion-native variant alongside the POSIX version. Do not force POSIX-only idioms that degrade the Nushell or Ion experience. |
| No Bashisms in shared scripts | Bash-only extensions (`[[ ]]`, `(( ))`, process substitution `<(...)`, `${var^^}`, indexed arrays) are prohibited in files intended for all four shells. Bash-specific scripts are permitted only when explicitly scoped (e.g., `#!/usr/bin/env bash` shebang, clearly labeled). |
| Graceful shell detection | Tools that need runtime shell detection must inform the user or degrade gracefully rather than silently failing in non-Bash environments. |

---

## §8 — Privacy-Friendly Application (PFA) Policy

Every Spacecraft Software application must satisfy **all three** PFA requirements:

Expand All @@ -410,7 +425,7 @@ or networking, verify all three PFA requirements are met.

---

## §8 — Key Bindings
## §9 — Key Bindings

All interactive applications must support **both**:

Expand All @@ -421,7 +436,7 @@ All interactive applications must support **both**:

---

## §9 — Spacecraft Software Color Palette (WCAG-Compliant)
## §10 — Spacecraft Software Color Palette (WCAG-Compliant)

The **only** permitted colors for Spacecraft Software interfaces and documents:

Expand All @@ -440,7 +455,7 @@ No alternative background is permitted. This is non-negotiable.
For document/file generation → load the `spacecraft-document-format` skill.
For IDE/terminal themes → load the `spacecraft-theme-factory` skill.

### §9.1 — Steelbore Theme (Application Theming Standard)
### §10.1 — Steelbore Theme (Application Theming Standard)

When building a new Spacecraft Software application (GUI, TUI, or web), all palette
references **must** be accessed through a named theme called **`Steelbore`** rather than
Expand Down Expand Up @@ -468,7 +483,7 @@ swap the theme, not every hex literal.

---

## §10 — Typography (FOSS-Licensed Fonts Only)
## §11 — Typography (FOSS-Licensed Fonts Only)

Acceptable font licenses: **OFL, Apache 2.0, Ubuntu Font License, CC0-1.0**

Expand All @@ -483,34 +498,34 @@ verify they are available on Google Fonts or another FOSS-licensed repository.

---

## §11 — UI/UX Design System
## §12 — UI/UX Design System

- **Material Design** is the required component system for all graphical applications.
Theme Material components with the §9 color palette.
Theme Material components with the §10 color palette.
- **WCAG 2.1 Level AA** contrast is the minimum for all color pairings.
Any new color additions must be WCAG-verified before adoption.
- **Accessibility:** screen readers, keyboard-only navigation, and system accessibility
preferences (reduced motion, high contrast) must all be respected.

---

## §12 — Date, Time & Units
## §13 — Date, Time & Units

### §12.1 — Date & Time Format Rules
### §13.1 — Date & Time Format Rules

| Concern | Rule | Example |
|--------------|------------------------------------------------------------------|------------------------------|
| Date format | ISO 8601 only: `YYYY-MM-DD` | `2026-03-08` |
| Time format | 24-hour only: `HH:MM:SS` — AM/PM is **never** permitted | `14:30:00` |
| Timestamp | Combined ISO 8601 UTC: `YYYY-MM-DDTHH:MM:SSZ` | `2026-03-08T14:30:00Z` |
| Timezone | **UTC Z is the default and preferred primary** for general-purpose, cross-system, and machine-readable timestamps. A project whose core domain is inherently local-time-bound (e.g., solar/prayer-time calculations) may declare local time as its primary record instead — a documented exception, not a free choice. See §12.2 and §12.2.1 | `Z` not `+00:00` |
| Timezone | **UTC Z is the default and preferred primary** for general-purpose, cross-system, and machine-readable timestamps. A project whose core domain is inherently local-time-bound (e.g., solar/prayer-time calculations) may declare local time as its primary record instead — a documented exception, not a free choice. See §13.2 and §13.2.1 | `Z` not `+00:00` |
| Duration | ISO 8601 duration format only | `PT1H30M` not "1h 30m" |
| Units | Metric (SI) primary; imperial in parentheses only if locale requires | `100 km (62 mi)` |

Apply these conventions to all generated code, documentation, comments, and any
user-facing strings. Never output AM/PM time, non-ISO dates, or imperial-primary units.

### §12.2 — UTC Z Timezone Policy
### §13.2 — UTC Z Timezone Policy

**UTC Z is the default and preferred timezone for stored, transmitted, logged,
and committed timestamps across Spacecraft Software projects.** It is the
Expand All @@ -522,11 +537,11 @@ as a secondary, human-convenience field — but UTC Z remains the authoritative
record.

This is a strong default, not a universal mandate forced onto every domain
regardless of fit — §12.2.1 documents the exception that lets a project whose
regardless of fit — §13.2.1 documents the exception that lets a project whose
domain is genuinely local-time-bound use local time as its primary record instead.

**Rules for projects under the UTC Z default — apply unless a project has filed
the §12.2.1 exception:**
the §13.2.1 exception:**

| Rule | Detail |
|------|--------|
Expand All @@ -537,7 +552,7 @@ the §12.2.1 exception:**
| Commit timestamps use UTC | `GIT_COMMITTER_DATE` and `GIT_AUTHOR_DATE` must be UTC when set programmatically. |
| File metadata written by Spacecraft Software tools | mtime/ctime written by Spacecraft Software tools must be UTC-sourced. |

### §12.2.1 — Domain Exception: Inherently Local-Time-Bound Projects
### §13.2.1 — Domain Exception: Inherently Local-Time-Bound Projects

A project whose core domain is fundamentally defined by **local civil or solar
time** — not by a moment in absolute (UTC) time — may declare local time as the
Expand All @@ -554,7 +569,7 @@ would misrepresent what the data actually is.
or user convenience.
2. **Keep the default everywhere else.** General-purpose machinery within the
same project — logs, commit timestamps, internal cross-system APIs,
telemetry — still follows the §12.2 UTC Z default. The exception covers the
telemetry — still follows the §13.2 UTC Z default. The exception covers the
domain data itself, not the whole project.
3. **Preserve UTC derivability.** Store or compute the IANA timezone (e.g.,
`Africa/Cairo`) alongside the local value, so a UTC instant remains derivable
Expand All @@ -563,15 +578,15 @@ would misrepresent what the data actually is.
convenient" or "our users are mostly in one timezone" do not qualify — the
domain itself must be inherently local-time-bound.

### §12.3 — Local Time as Optional Companion
### §13.3 — Local Time as Optional Companion

**For projects under the UTC Z default** (§12.2), local time expressed as a UTC
**For projects under the UTC Z default** (§13.2), local time expressed as a UTC
offset is permitted as an **optional companion** to the UTC Z primary value — in
human-facing display, in API responses (as an additional field, never replacing
the UTC Z field), and in stored records where timezone context aids human
readers. The UTC Z value is always present and always authoritative; the
local-time companion is supplemental only. (A project operating under the
§12.2.1 domain exception inverts these roles for its domain data — local time is
§13.2.1 domain exception inverts these roles for its domain data — local time is
primary there, with UTC kept derivable rather than displayed as authoritative.)

- The `--absolute-time` flag (defined in `spacecraft-cli-standard` §3) disables
Expand All @@ -583,7 +598,7 @@ primary there, with UTC kept derivable rather than displayed as authoritative.)
4. Never persist or transmit the local-time rendering.
- JSON/machine output (`--format json/jsonl/yaml/csv`) MUST always use UTC + `Z`.

### §12.4 — Duration Format
### §13.4 — Duration Format

Durations follow ISO 8601 duration notation:

Expand All @@ -596,7 +611,7 @@ Durations follow ISO 8601 duration notation:
Prose forms like "1h 30m", "90 minutes", "1.5 hours" are **forbidden** in
machine-readable output. They are acceptable in `--help` text only.

### §12.5 — Rust Implementation Guidance
### §13.5 — Rust Implementation Guidance

When writing Rust code that handles time:

Expand All @@ -612,14 +627,14 @@ When writing Rust code that handles time:

---

## §13 — Attribution, Maintainer & Contact
## §14 — Attribution, Maintainer & Contact

**Maintainer:** Mohamed Hammad
**Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
**Copyright:** Copyright (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
**Website:** [https://SpacecraftSoftware.org/](https://SpacecraftSoftware.org/)

### §13.1 — Project Pages
### §14.1 — Project Pages

Each Spacecraft Software project has a dedicated subdomain following the pattern
`https://<ProjectName>.SpacecraftSoftware.org/`. Use the project-specific URL in all
Expand Down Expand Up @@ -653,7 +668,7 @@ project-level outputs; use `https://SpacecraftSoftware.org/` only for umbrella r

When a new project is created, add its subdomain to this table immediately.

### §13.2 — Mandatory Attribution in Project Outputs
### §14.2 — Mandatory Attribution in Project Outputs

Every Spacecraft Software product **must** surface the following attribution in at least one
of: `--help` output, `--version` output, README, or About/Info screen.
Expand Down Expand Up @@ -693,16 +708,22 @@ https://<ProjectName>.SpacecraftSoftware.org/
"maintainer": "Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>",
"website": "https://<ProjectName>.SpacecraftSoftware.org/"
```
- **Email obfuscation in plain-text prose.** In plain-text prose contexts (README body,
CONTRIBUTING.md, human-readable documentation) where the address is not a clickable
link, `Mohamed.Hammad [at] SpacecraftSoftware.org` is permitted as a scraper-resistant
form. `# Maintainer:` lines in PKGBUILDs and `SPDX-FileCopyrightText` headers **must**
always use the full address — those formats are parsed by `makepkg`/`pkgcheck` and
`reuse lint` respectively, and obfuscation breaks them.

### §13.3 — Third-Party Attribution
### §14.3 — Third-Party Attribution

Spacecraft Software artifacts must give credit where credit is due. When a project
or skill **substantially builds on third-party work**, that credit appears
in a `CREDITS.md` at the artifact's root — `<project-root>/CREDITS.md` for
projects, `<skill-name>/CREDITS.md` for skills.

`CREDITS.md` is the inbound counterpart to §13.2's outbound attribution:
§13.2 tells consumers who maintains Spacecraft Software; §13.3 tells consumers whose
`CREDITS.md` is the inbound counterpart to §14.2's outbound attribution:
§14.2 tells consumers who maintains Spacecraft Software; §14.3 tells consumers whose
work Spacecraft Software stands on.

**Triggers** (any one obligates a `CREDITS.md`):
Expand Down Expand Up @@ -744,7 +765,7 @@ shaped the Spacecraft Software artifact.

---

## §14 — Compliance Checklist (Audit Gate)
## §15 — Compliance Checklist (Audit Gate)

Before finalising **any** Spacecraft Software artifact, mentally verify:

Expand All @@ -758,14 +779,15 @@ Before finalising **any** Spacecraft Software artifact, mentally verify:
- [ ] **§5** Project Posture: README/NOTICE/CONTRIBUTING present; default personal-hobby stance applied; general-use carve-outs declared in project README
- [ ] **§5.5** Package distribution: `packaging/guix.scm`, `packaging/default.nix`, and `packaging/PKGBUILD` present, buildable, and carrying correct version + SHA-256 checksum (in each package manager's native format) before any release tag is pushed
- [ ] **§6.1** POSIX-compliant CLI/system tools
- [ ] **§7** PFA: no tracking, minimal permissions, local storage default
- [ ] **§8** CUA + Vim-like key bindings planned/implemented
- [ ] **§9** Spacecraft Software color palette used; Void Navy background mandatory; new apps expose colors via a named `Steelbore` theme (§9.1) — no bare hex literals in UI logic
- [ ] **§10** FOSS-licensed fonts only (Share Tech Mono / Inconsolata)
- [ ] **§11** Material Design UI/UX; WCAG 2.1 AA verified
- [ ] **§12** ISO 8601 dates; 24h time; UTC Z is the default primary timestamp (companion local time with UTC offset permitted, never a replacement) — unless the project filed the §12.2.1 domain exception for inherently local-time-bound data; ISO 8601 durations; metric units
- [ ] **§13** Attribution present: maintainer name (`Mohamed Hammad`), contact (`Mohamed.Hammad@SpacecraftSoftware.org`), and project URL in `--version` / README / About
- [ ] **§13.3** Third-party work credited in `CREDITS.md` at project/skill root when triggers apply; deeper `references/ATTRIBUTION.md` present where reference content is adapted from external sources
- [ ] **§7** Shell scripts are POSIX-compatible; Nushell/Ion native variants provided where shell-native idioms are required; no Bashisms in shared scripts
- [ ] **§8** PFA: no tracking, minimal permissions, local storage default
- [ ] **§9** CUA + Vim-like key bindings planned/implemented
- [ ] **§10** Spacecraft Software color palette used; Void Navy background mandatory; new apps expose colors via a named `Steelbore` theme (§10.1) — no bare hex literals in UI logic
- [ ] **§11** FOSS-licensed fonts only (Share Tech Mono / Inconsolata)
- [ ] **§12** Material Design UI/UX; WCAG 2.1 AA verified
- [ ] **§13** ISO 8601 dates; 24h time; UTC Z is the default primary timestamp (companion local time with UTC offset permitted, never a replacement) — unless the project filed the §13.2.1 domain exception for inherently local-time-bound data; ISO 8601 durations; metric units
- [ ] **§14** Attribution present: maintainer name (`Mohamed Hammad`), contact (`Mohamed.Hammad@SpacecraftSoftware.org`), and project URL in `--version` / README / About
- [ ] **§14.3** Third-party work credited in `CREDITS.md` at project/skill root when triggers apply; deeper `references/ATTRIBUTION.md` present where reference content is adapted from external sources
- [ ] **§6.3** All commits to Spacecraft Software Git remotes cryptographically signed with the `Mohamed.Hammad@SpacecraftSoftware.org` key and showing "Verified" on the hosting platform; rewrites preserve signatures; programmatic and assistant-driven commits signed too

If any item is not applicable to the current artifact type (e.g., color palette
Expand All @@ -775,12 +797,13 @@ for a pure Rust library), note it as N/A rather than silently skipping it.

## Skill Cross-References

| Task | Load this skill |
|---------------------------------------|------------------------------|
| Writing any Rust code | `microsoft-rust-guidelines` |
| Generating DOCX / ODT / PDF documents | `spacecraft-document-format` |
| Creating IDE / terminal themes | `spacecraft-theme-factory` |
| All other Spacecraft Software work | `spacecraft-standard` |
| Task | Load this skill |
|---------------------------------------|----------------------------------------------------|
| Writing any Rust code | `microsoft-rust-guidelines` |
| Writing or reviewing shell scripts | `spacecraft-cli-shell` + `spacecraft-cli-preference` |
| Generating DOCX / ODT / PDF documents | `spacecraft-document-format` |
| Creating IDE / terminal themes | `spacecraft-theme-factory` |
| All other Spacecraft Software work | `spacecraft-standard` |

---

Expand Down
Loading