From 16ad03926b31eddde9714a240b1ab8fc2e50d319 Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 23:10:15 -0400 Subject: [PATCH 1/5] docs(standards): add org engineering standards + restyle README template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Engineering guidelines (docs/standards/): - README.md — index, the standard-stack table, enforcement model - 01-baseline — Tier 1: required toolchain, hard rules, code shape (all repos) - 02-languages — Tier 2: per-language tooling/idioms (TS, Py, C#, Rust, C/C++, sh, SQL, md/json/yaml) - 03-safety-overlay — Tier 3: JSF AV C++ / MISRA / NASA Power of Ten for device- & flight-adjacent code - 04-security — security overlay (OWASP/CERT, secrets, web headers, crypto/auth) Linked from README.md and CONTRIBUTING.md (new "Engineering standards" section). CONTRIBUTING onboarding: collapse the two-curl flow to the single `curl -fsSL https://get.resq.software | sh` (install.sh does CLI + hooks). README template restyle (editorial / centered): - one centered hero
— mark, title, tagline, calm flat badge row (logos + the ResQ sky accent 0ea5e9), single nav line, ◆ divider. - new ## Stats section: Repobeats activity embed + contrib.rocks avatars. - TOC updated; all internal links verified to resolve. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTRIBUTING.md | 27 +++++-- README.md | 1 + README.template.md | 117 +++++++++++++--------------- docs/standards/01-baseline.md | 69 ++++++++++++++++ docs/standards/02-languages.md | 101 ++++++++++++++++++++++++ docs/standards/03-safety-overlay.md | 84 ++++++++++++++++++++ docs/standards/04-security.md | 60 ++++++++++++++ docs/standards/README.md | 66 ++++++++++++++++ 8 files changed, 453 insertions(+), 72 deletions(-) create mode 100644 docs/standards/01-baseline.md create mode 100644 docs/standards/02-languages.md create mode 100644 docs/standards/03-safety-overlay.md create mode 100644 docs/standards/04-security.md create mode 100644 docs/standards/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 789ab57..6125bd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,17 +4,13 @@ Thanks for your interest. This guide applies to every repository under [`resq-so ## Onboarding -Two curls get you from a bare machine to a working ResQ dev loop: +One curl gets you from a bare machine to a working ResQ dev loop: ```bash -# 1. Install the `resq` CLI (SHA-verified release binary, cargo fallback) -curl -fsSL https://raw.githubusercontent.com/resq-software/dev/main/scripts/install-resq.sh | sh - -# 2. Inside a cloned ResQ repo, install the canonical git hooks -cd && curl -fsSL https://raw.githubusercontent.com/resq-software/dev/main/scripts/install-hooks.sh | sh +curl -fsSL https://get.resq.software | sh ``` -The second script installs six hooks (pre-commit, commit-msg, prepare-commit-msg, pre-push, post-checkout, post-merge) that delegate to `resq pre-commit`. It also offers to scaffold a repo-type-aware `local-pre-push` (Rust / Python / Node / .NET / C++ / Nix). +This installs the SHA256-verified `resq` CLI (with a `cargo install --git` fallback), optionally clones a repo, and — when run inside a repo — installs the canonical git hooks: six hooks (pre-commit, commit-msg, prepare-commit-msg, pre-push, post-checkout, post-merge) that delegate to `resq pre-commit`, plus an offer to scaffold a repo-type-aware `local-pre-push` (Rust / Python / Node / .NET / C++ / Nix). Full contract: [`resq-software/dev/AGENTS.md#git-hooks`](https://github.com/resq-software/dev/blob/main/AGENTS.md#git-hooks). @@ -57,6 +53,23 @@ resq hooks doctor # report drift between installed and canonical hooks resq hooks update # rewrite installed hooks from embedded templates ``` +## Engineering standards + +Org-wide code standards live in [`docs/standards/`](./docs/standards/) — a +three-tier model: + +- [**Tier 1 — Baseline**](./docs/standards/01-baseline.md): required toolchain, + hard rules, code shape (every repo). +- [**Tier 2 — Language enforcement**](./docs/standards/02-languages.md): per-language + tooling and idioms (TS, Python, C#, Rust, C/C++, Shell, SQL, …). +- [**Tier 3 — Safety overlay**](./docs/standards/03-safety-overlay.md): JSF / MISRA / + NASA Power of Ten for device- and flight-adjacent code. +- [**Security overlay**](./docs/standards/04-security.md): untrusted input, secrets, + auth, crypto. + +Per-repo specifics (commands, architecture, deliberate deviations) still live in +each repo's `AGENTS.md`. + ## Opening a PR 1. Branch from the default branch; name it per the pattern above. diff --git a/README.md b/README.md index dc6be36..c0ef89b 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Organization-wide community health files, issue/PR templates, and the public pro | `profile/README.md` | The org profile shown at [github.com/resq-software](https://github.com/resq-software) | | `assets/` | Shared assets (banner, logo) used across org READMEs | | `README.template.md` | Standardized README template for new ResQ repositories | +| [`docs/standards/`](docs/standards/) | Org-wide engineering standards — the three-tier model (baseline, per-language, safety overlay) + security overlay | ### Community Health Files diff --git a/README.template.md b/README.template.md index 3e69273..c8f37ea 100644 --- a/README.template.md +++ b/README.template.md @@ -16,86 +16,52 @@ ═══════════════════════════════════════════════════════════════════ --> - -

- {{PROJECT_NAME}} Banner -

+ +
+ + +{{PROJECT_NAME}}

{{PROJECT_NAME}}

- -

- {{ONE_LINE_DESCRIPTION}} -

- - - ── Version ───────────────────────────────────────────────────────── - npm: https://img.shields.io/npm/v/{{NPM_PACKAGE}} - crates: https://img.shields.io/crates/v/{{CRATE_NAME}} - PyPI: https://img.shields.io/pypi/v/{{PYPI_PACKAGE}} - NuGet: https://img.shields.io/nuget/v/{{NUGET_PACKAGE}} - - ── Coverage ───────────────────────────────────────────────────────── - https://codecov.io/gh/resq-software/{{REPO}}/graph/badge.svg - - ── License (Apache-2.0, all ResQ projects) ───────────────────────── - https://img.shields.io/badge/license-Apache--2.0-blue.svg ---> -

- - - CI - - - - - npm version - - - - crates.io - - - - PyPI - - - - NuGet - - - - Coverage - - - - License: Apache-2.0 - - - - Total Stars - -

+[![CI](https://img.shields.io/github/actions/workflow/status/resq-software/{{REPO}}/ci.yml?branch=main&style=flat&logo=githubactions&logoColor=white&label=ci&color=0ea5e9)](https://github.com/resq-software/{{REPO}}/actions/workflows/ci.yml) +[![npm](https://img.shields.io/npm/v/{{NPM_PACKAGE}}?style=flat&logo=npm&label=npm&color=0ea5e9)](https://www.npmjs.com/package/{{NPM_PACKAGE}}) +[![crates.io](https://img.shields.io/crates/v/{{CRATE_NAME}}?style=flat&logo=rust&logoColor=white&color=0ea5e9)](https://crates.io/crates/{{CRATE_NAME}}) +[![PyPI](https://img.shields.io/pypi/v/{{PYPI_PACKAGE}}?style=flat&logo=pypi&logoColor=white&color=0ea5e9)](https://pypi.org/project/{{PYPI_PACKAGE}}/) +[![NuGet](https://img.shields.io/nuget/v/{{NUGET_PACKAGE}}?style=flat&logo=nuget&logoColor=white&color=0ea5e9)](https://www.nuget.org/packages/{{NUGET_PACKAGE}}) +[![Coverage](https://codecov.io/gh/resq-software/{{REPO}}/graph/badge.svg)](https://codecov.io/gh/resq-software/{{REPO}}) +[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0ea5e9?style=flat)](./LICENSE) -

Documentation  ·  Website  ·  - Quick Start + Quick Start  ·  - Report Bug + Report Bug  ·  - Request Feature + Request Feature

+
+ +

◆   ◆   ◆

+ --- @@ -115,6 +81,7 @@ - [Changelog](#changelog) - [License](#license) - [Acknowledgements](#acknowledgements) +- [Stats](#stats) --- @@ -385,6 +352,26 @@ Licensed under the [Apache License, Version 2.0](./LICENSE). --- +## Stats + + + +
+ +![{{PROJECT_NAME}} activity](https://repobeats.axiom.co/api/embed/{{REPOBEATS_HASH}}.svg "Repobeats analytics image") + + + + Contributors + + +
+ +--- + -{{PROJECT_NAME}} +{{PROJECT_NAME}}

{{PROJECT_NAME}}

From 3209caac89a15b422f8ffbd8f860f077c0ced796 Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 23:13:07 -0400 Subject: [PATCH 3/5] Update docs/standards/04-security.md Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> Signed-off-by: Mike Odnis --- docs/standards/04-security.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/standards/04-security.md b/docs/standards/04-security.md index 77f24e6..bd649e0 100644 --- a/docs/standards/04-security.md +++ b/docs/standards/04-security.md @@ -7,16 +7,14 @@ This is the day-to-day checklist; the disclosure process lives in ## Pre-merge checklist -```text -[ ] No hardcoded secrets (API keys, passwords, tokens). -[ ] All user input validated at the boundary (schema-based where possible). -[ ] SQL: parameterized queries only — no string concatenation. -[ ] XSS: output encoded; no unsanitized HTML injection. -[ ] CSRF protection on state-changing requests. -[ ] AuthN/AuthZ verified on every protected path; fail closed. -[ ] Rate limiting on public / abusable endpoints. -[ ] Error messages don't leak secrets, stack traces, or PII. -``` +- [ ] No hardcoded secrets (API keys, passwords, tokens). +- [ ] All user input validated at the boundary (schema-based where possible). +- [ ] SQL: parameterized queries only — no string concatenation. +- [ ] XSS: output encoded; no unsanitized HTML injection. +- [ ] CSRF protection on state-changing requests. +- [ ] AuthN/AuthZ verified on every protected path; fail closed. +- [ ] Rate limiting on public / abusable endpoints. +- [ ] Error messages don't leak secrets, stack traces, or PII. ## Secret management From f14d7a2428f58d19264dba1f654665a81db96890 Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 23:19:02 -0400 Subject: [PATCH 4/5] docs(standards): align tier wording + fix security-scan link target MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CONTRIBUTING.md: "three-tier model:" → "three-tier model plus a security overlay:" so the lead-in matches the four bullets (3 tiers + the security overlay). Kept Security as an *overlay* rather than relabeling it "Tier 4", to stay consistent with docs/standards/README.md ("The three tiers") and 04-security.md ("Composes with all three tiers"). - 04-security.md: point the `security-scan.yml` link at the actual workflow file (../../.github/workflows/security-scan.yml) so text and href match. Skipped the suggested README.md edit: it already reads "the three-tier model (…) + security overlay", which is correct; switching it to "four-tier" would introduce the contradiction the other docs avoid. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTRIBUTING.md | 2 +- docs/standards/04-security.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6125bd4..800cea4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ resq hooks update # rewrite installed hooks from embedded templates ## Engineering standards Org-wide code standards live in [`docs/standards/`](./docs/standards/) — a -three-tier model: +three-tier model plus a security overlay: - [**Tier 1 — Baseline**](./docs/standards/01-baseline.md): required toolchain, hard rules, code shape (every repo). diff --git a/docs/standards/04-security.md b/docs/standards/04-security.md index bd649e0..1e9ecf7 100644 --- a/docs/standards/04-security.md +++ b/docs/standards/04-security.md @@ -23,7 +23,7 @@ This is the day-to-day checklist; the disclosure process lives in - Rotate anything that may have been exposed; treat exposure as an incident. - GitHub native secret scanning + push protection are on; CI runs OSV/Dependency Review, with opt-in Gitleaks/Semgrep/Snyk (see - [`security-scan.yml`](../../.github/workflows/README.md)). + [`security-scan.yml`](../../.github/workflows/security-scan.yml)). ## Reference standards From d4e10c41665b9e2728a9f082105a26cb0e61dadc Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 23:21:04 -0400 Subject: [PATCH 5/5] docs(standards): move #![forbid(unsafe_code)] out of the cargo command block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It's a Rust source-level attribute, not a CLI command — list it as a prose bullet instead (addresses gemini review on PR #24). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/standards/02-languages.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/standards/02-languages.md b/docs/standards/02-languages.md index 92daeb0..72e96e6 100644 --- a/docs/standards/02-languages.md +++ b/docs/standards/02-languages.md @@ -57,9 +57,10 @@ cargo clippy -- -D warnings cargo test cargo audit cargo deny check -#![forbid(unsafe_code)] // where the crate allows it ``` +- Add `#![forbid(unsafe_code)]` at the crate root where the crate allows it + (it's a source attribute, not a CLI flag). - Follow the [Rust API Guidelines](https://github.com/rust-lang/api-guidelines) for public surfaces. - Treat every `unsafe` block as a mini C island: document the invariants,