diff --git a/AGENTS.md b/AGENTS.md index 9056482..b7b4dc4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ The umbrella was renamed from `Steelbore` to `Spacecraft Software` in v1.7 (2026 ## Source-of-truth flow ``` -/spacecraft-software/construct/spacecraft-standard-constitution/SKILL.md (upstream — the canonical skill) +/spacecraft-software/construct/spacecraft-steelbore-standard/SKILL.md (upstream — the canonical skill) │ ▼ manual sync when the skill changes /spacecraft-software/standard/The_Steelbore_Standard.texi (tracked — Texinfo source of truth) @@ -62,7 +62,7 @@ There is **no document-build step in CI** — keep the local `makeinfo` check as ## 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/construct/spacecraft-steelbore-standard/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 @@ -81,7 +81,7 @@ The skill's own metadata may lag; the published standard's version history is th ## 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. +- **A normative change is a two-repo, two-PR job.** The rule lives in `The_Steelbore_Standard.texi` (here) *and* in `spacecraft-steelbore-standard/SKILL.md` + `references/CHANGELOG.md` (Construct). Land them as separate PRs — typically Standard first, Construct second — at the same version. ## Self-applies diff --git a/CHANGELOG.md b/CHANGELOG.md index 5b4da6b..12dc17f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,13 +13,14 @@ its generated `The_Steelbore_Standard.md` companion; §1 — Preamble carries a pointer here rather than the full history, so the published document stays about the rules in force rather than how they got there. The skill encoding of the standard keeps a parallel history at -`construct/spacecraft-standard-constitution/references/CHANGELOG.md`, which must +`construct/spacecraft-steelbore-standard/references/CHANGELOG.md`, which must be synced to the same version and date. Entries are newest-first. Dates are UTC, ISO 8601 (§14). Versioning policy: bump for upstream skill changes, registry updates (§2.1, §15.1), factual corrections to normative content, and brand/identity changes. +- **v1.49 (2026-08-16):** **Skill renamed: `spacecraft-standard-constitution` → `spacecraft-steelbore-standard`.** The skill encoding of this Standard now carries the document's own canonical name — "The Steelbore Standard" has been the document's stable name since the v1.8 reinstatement, and the skill id now says so instead of the generic "constitution". Skill ids are §2.2 functional identifiers, so no codename rule is engaged. The Standard names the skill in four places — the §1 changelog-location note, the §2.2 exemption example, the §4.1.1 licensing note, and the Skill Cross-References table — and all four now carry the new id, as does this file's header pointer to the skill's parallel changelog. As v1.44 recorded, a cross-reference is normative content and renaming a skill is a two-repo edit: the Construct-side rename (directory, frontmatter `name:`, catalogue row, CI version-pin exemption, sibling-skill cross-references, repacked bundles) lands as its own PR at this same version and date. Same-day bump with different content, so it increments past v1.48 rather than sharing it (the v1.30/v1.31 precedent). No rule changes; every §17 clause is exactly as v1.48 left it. - **v1.48 (2026-08-16):** **§17.2 simplified — the MVP row joins the single cell style.** v1.47 set the `MVP` row apart in `▰` (U+25B0) / `▱` (U+25B1) with padded brackets, `[ `…` ]`, on the argument that the headline figure should be findable at a glance in a stack of otherwise identical bars. In practice the distinction bought less than it cost: the padded row needed its own label-field width (five characters where every other row uses six), its own bracket geometry, its own percentage-separator rule (one space where the others use two), and a documented edge case in which the two row types stop aligning at exactly 100% — four special cases carried by every emitter and checker of the format, to distinguish a row that its fixed position (always immediately after the last milestone) and its label already distinguish. **§17.2 now defines one cell style for every row** — milestones, `MVP`, `TODO`, `PLAN`, and `PRD` alike: `█` (U+2588) filled, `░` (U+2591) empty, tight brackets with no space inside either. The `▰`/`▱` pair, the whole of §17.2 from v1.32 until v1.47 narrowed it to the MVP row alone, is now retired entirely. The alignment rules collapse from five bullets to three, all universal: label and colon left-aligned in a six-character field followed by `[`; first bar cell in column 8, bars occupying columns 8–27, `]` in column 28; percentage right-aligned in a five-character field so `%` lands in column 33 whether the value is one, two, or three digits. The v1.47 misalignment-at-100% carve-out disappears rather than being restated — with tight brackets and a two-space separator, a 100% value consumes one separator space and the block stays aligned at every value. Unchanged: §17.1's row set, fixed order, and only-applicable-rows rule; the cell-count rounding and its two saturation rules; the prohibition on ASCII bars. §16's §17 bullet drops the two-style clause. This lands before v1.47's `▰`/`▱` MVP carve-out ever merged to the Standard's `main`, but the Construct skill published v1.47 on its own `main` on 2026-08-09, so per the versioning policy this is an increment, not an in-place revision. - **v1.47 (2026-08-09):** **§17.1 and §17.2 rewritten — progress reports become a labelled-row block.** The format §17.1 has carried since the section was written packed every figure into three dense lines: a single unlabelled bar, then all milestones pipe-separated on one line, then MVP and PRD sharing a third. Only one of those numbers — the PRD total — ever got a bar, so the milestones and the MVP were reported as bare percentages while the least granular figure got the only visual. Reading it meant parsing a run-on line to find the milestone you cared about, and comparing two milestones meant comparing two integers rather than two bars. The replacement gives **every track its own row, its own 20-cell bar, and its own percentage**, in a fixed order: milestone rows `M0`…`Mn` ascending, then `MVP`, then `TODO`, then `PLAN`, then `PRD`. **`TODO` and `PLAN` are new tracks** — the old format had no way to report against a plan document or a task list at all, so work driven by either was reported against a PRD that did not exist. **Only applicable rows are emitted**, and this is a rule rather than a convenience: the milestone rows match the milestones the plan actually defines (`M0`–`M4` in the template is an illustration, not a required set), `TODO`/`PLAN`/`PRD` appear only when the task is driven by such an artifact, and `MVP` is always present. Padding the block out with fabricated 0% rows is forbidden — a track that does not exist reports progress against nothing, and a reader cannot tell a genuine zero from a placeholder. **§17.2 now defines two cell styles, and the distinction is normative.** Milestone, `TODO`, `PLAN` and `PRD` rows use `█` (U+2588) filled and `░` (U+2591) empty with tight brackets; the `MVP` row uses `▰` (U+25B0) and `▱` (U+25B1) with padded brackets, `[ `…` ]`. MVP is the headline figure and the rows around it are the inputs that feed it, so it is set in a different glyph pair to stay findable at a glance in a stack of otherwise identical bars — the `▰`/`▱` pair that was the whole of §17.2 before this version is retained for exactly that one row rather than retired. **Column alignment is normative, and the bracket padding is what preserves it**: the MVP row is one character narrower in its label field and one character wider inside each bracket, so every bar cell and every percentage digit lands in the same column across the whole block. Stated as rules — label-plus-colon left-aligned in a six-character field on every row but MVP, five on MVP followed by `[` and a space; every bar in columns 8 through 27 on both; percentage right-aligned so its `%` lands in the same column on every row, which means two spaces after the closing bracket on the tight rows and one on `MVP`, with the separator never dropping below one space (so at 100% the `MVP` percentage sits one column right — the only value at which the two row types do not align, and preferable to a bracket abutting a digit). **Cell count is specified for the first time.** The old text said "20-character" and left the mapping from percentage to cells entirely unstated, so 43% could legitimately render as 8 cells or 9. It is now the percentage scaled to twenty cells and rounded to the nearest cell, with two saturation rules overriding the rounding: twenty filled cells **only** at exactly 100%, zero filled **only** at exactly 0%. Rounding 99% up to a visually complete bar reports work as finished that is not — precisely the drift §17 exists to catch. Unchanged: **§17.3's cadence** (baseline at task start, at each milestone completion, and in the end-of-turn summary), and the prohibition on legacy ASCII bars, now stated for `#`, `-` and `=` and binding on every row rather than on "the progress bar" singular. §16's §17 checklist bullet is rewritten from the old three-figure summary to the row-block form. - **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. diff --git a/The_Steelbore_Standard.md b/The_Steelbore_Standard.md index 8eb80bf..cfce0ad 100644 --- a/The_Steelbore_Standard.md +++ b/The_Steelbore_Standard.md @@ -29,9 +29,9 @@ 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.48**, updated 2026-08-16 (§14: UTC, ISO +This document is **version 1.49**, updated 2026-08-16 (§14: UTC, ISO 8601). The skill encoding of the standard keeps a parallel history in -`spacecraft-standard-constitution/references/CHANGELOG.md` in the +`spacecraft-steelbore-standard/references/CHANGELOG.md` in the [Construct repository](https://github.com/Spacecraft-Software/Construct); both are synced to the same version and date. @@ -131,7 +131,7 @@ commit. ## §2.2 — Skill IDs are functional, not codenamed Skill directory names and `SKILL.md` `name` fields are **functional -identifiers** (e.g., `spacecraft-standard-constitution`, +identifiers** (e.g., `spacecraft-steelbore-standard`, `spacecraft-document-format`) and are not subject to the §2 codename convention. §2 reserves codenames for projects/modules/utilities/releases, not for skill identifiers. @@ -359,8 +359,8 @@ Skills are **software-class** → `GPL-3.0-or-later` (no skill is network-facing, so AGPL does not apply). Note the deliberate split for the Standard itself: the **published Standard document** is `CC-BY-SA-4.0` (it is a document), while its -`spacecraft-standard-constitution` **skill** encoding is -`GPL-3.0-or-later` (it is a skill). +`spacecraft-steelbore-standard` **skill** encoding is `GPL-3.0-or-later` +(it is a skill). ## §4.2 — Upstream License Compliance (preserve what you build on) @@ -2552,6 +2552,6 @@ skipping it. | 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` | +| All other Spacecraft Software work | `spacecraft-steelbore-standard` | # Concept Index diff --git a/The_Steelbore_Standard.texi b/The_Steelbore_Standard.texi index 5e25dba..3bee46a 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.48 +@settitle The Steelbore Standard 1.49 @c %**end of header -@set VERSION 1.48 +@set VERSION 1.49 @set UPDATED 2026-08-16 @set SUBDOMAIN https://Standard.SpacecraftSoftware.org/ @@ -115,7 +115,7 @@ they got there. This document is @strong{version @value{VERSION}}, updated @value{UPDATED} (§14: UTC, ISO 8601). The skill encoding of the standard keeps a parallel history in -@file{spacecraft-standard-constitution/references/CHANGELOG.md} in the +@file{spacecraft-steelbore-standard/references/CHANGELOG.md} in the @uref{https://github.com/Spacecraft-Software/Construct,Construct repository}; both are synced to the same version and date. @@ -308,7 +308,7 @@ commit. @node Skill IDs @section §2.2 — Skill IDs are functional, not codenamed Skill directory names and @code{SKILL.md} @code{name} fields are -@strong{functional identifiers} (e.g., @code{spacecraft-standard-constitution}, +@strong{functional identifiers} (e.g., @code{spacecraft-steelbore-standard}, @code{spacecraft-document-format}) and are not subject to the §2 codename convention. §2 reserves codenames for projects/modules/utilities/releases, not for skill identifiers. @@ -622,7 +622,7 @@ Skills are @strong{software-class} → @code{GPL-3.0-or-later} (no skill is network-facing, so AGPL does not apply). Note the deliberate split for the Standard itself: the @strong{published Standard document} is @code{CC-BY-SA-4.0} (it is a document), while its -@code{spacecraft-standard-constitution} @strong{skill} encoding is +@code{spacecraft-steelbore-standard} @strong{skill} encoding is @code{GPL-3.0-or-later} (it is a skill). @node Upstream License @@ -4339,7 +4339,7 @@ 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} + @tab @code{spacecraft-steelbore-standard} @end multitable @node Concept Index