From cf4cfcd9772e6ede978aee2f86fc34cc35c5172c Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 02:17:41 -0400 Subject: [PATCH 1/3] feat(standards): repo-conformance check + get.resq.software install line Add a reusable repo-standards.yml that validates template/standards conformance: a detectable LICENSE, a non-stub README.md with a title, and no unrendered {{PLACEHOLDER}} template tokens (threshold-based, so docs that merely mention the syntax don't false-trip). Wire it into required.yml so every consumer repo inherits it through the existing `required` status check, and into required-gate.yml to dogfood it on this repo. Warn-by-default (annotations only), matching the org's audit->enforce pattern (harden-runner audit, rulesets evaluate); pass `repo-standards-strict: true` to required.yml to turn violations into a hard failure once a repo is clean. Adopt the new get.resq.software install endpoint: - profile/README.md: collapse the two-curl onboarding to a single `curl -fsSL https://get.resq.software | sh` (install.sh performs both the SHA256-verified binary install and the git-hook setup). - README.template.md: add a "ResQ CLI" install block with the one-liner plus an inspect-before-run variant. - .github/workflows/README.md: document repo-standards.yml and the strict toggle. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/workflows/README.md | 34 ++++++++ .github/workflows/repo-standards.yml | 124 +++++++++++++++++++++++++++ .github/workflows/required-gate.yml | 17 +++- .github/workflows/required.yml | 21 ++++- README.template.md | 21 +++++ profile/README.md | 16 ++-- 6 files changed, 225 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/repo-standards.yml diff --git a/.github/workflows/README.md b/.github/workflows/README.md index 583e188..9ae3d34 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -3,6 +3,40 @@ Org-wide CI building blocks. Callable from any `resq-software/*` repo via `uses: resq-software/.github/.github/workflows/.yml@main`. +## `repo-standards.yml` + +Template/standards conformance check. Validates that a repo has a detectable +`LICENSE`, a non-stub `README.md` with a title, and no leftover +`{{PLACEHOLDER}}` tokens or `ResQ README Template` scaffold markers. + +It is already wired into `required.yml` (so every consumer repo inherits it +through the `required` status check) and into `required-gate.yml` (so this +repo dogfoods it). You don't call it directly unless you want a standalone +conformance job. + +**Warn-by-default**, matching the org's audit → enforce pattern +(harden-runner audit, rulesets evaluate). Violations surface as +`::warning` annotations without failing the build. Once a repo is clean, +flip enforcement on by passing `repo-standards-strict: true` to +`required.yml`: + +```yaml +jobs: + ci: + uses: resq-software/.github/.github/workflows/required.yml@main + with: + lang: rust + repo-standards-strict: true # turn conformance violations into a hard failure +``` + +### Inputs (when called directly) + +| Input | Type | Default | Notes | +| :-- | :-- | :-- | :-- | +| `strict` | bool | `false` | Fail the job on any violation. Default warns only. | +| `require-license` | bool | `true` | Require a `LICENSE`/`COPYING` file at the repo root. | +| `readme-min-bytes` | string | `"500"` | README smaller than this is treated as a stub. | + ## `security-scan.yml` Defense-in-depth security scan. All third-party `uses:` refs are SHA-pinned diff --git a/.github/workflows/repo-standards.yml b/.github/workflows/repo-standards.yml new file mode 100644 index 0000000..3266d88 --- /dev/null +++ b/.github/workflows/repo-standards.yml @@ -0,0 +1,124 @@ +# Copyright 2026 ResQ Software +# SPDX-License-Identifier: Apache-2.0 +# +# Reusable repo-conformance check. Validates that a consumer repo meets +# the org template/standards baseline: +# * a detectable LICENSE file (Apache-2.0 across the org) +# * a non-stub README.md with a title and no leftover template tokens +# * no unrendered {{PLACEHOLDER}} tokens or template scaffold markers +# +# Wired into required.yml (consumer repos) and required-gate.yml (this +# repo), so the single `required` status check (gated by org ruleset +# `default-branch-baseline`, id 15191038) also covers template +# conformance. Warn-by-default to match the org's audit -> enforce +# rollout pattern (harden-runner audit, rulesets evaluate). Flip +# `strict: true` once a repo is clean to turn violations into a hard +# CI failure. +# +# Security: inputs that reach `run:` are forwarded through `env:` and +# referenced as "$VAR" to prevent template-time expansion of +# caller-controlled strings into the shell. + +name: repo-standards + +on: + workflow_call: + inputs: + strict: + description: Fail the job on any violation. Default warns (annotations only). + type: boolean + required: false + default: false + require-license: + description: Require a detectable LICENSE/COPYING file at the repo root. + type: boolean + required: false + default: true + readme-min-bytes: + description: Minimum README.md size in bytes; smaller is treated as a stub. + type: string + required: false + default: "500" + +permissions: + contents: read + +jobs: + repo-standards: + name: repo-standards + runs-on: ubuntu-latest + steps: + - name: Harden Runner + uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176 # v2 + with: + egress-policy: audit + + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + + - name: Check repo conformance + env: + STRICT: ${{ inputs.strict }} + REQUIRE_LICENSE: ${{ inputs.require-license }} + README_MIN_BYTES: ${{ inputs.readme-min-bytes }} + run: | + set -eu + violations=0 + note() { + printf '::warning title=repo-standards::%s\n' "$1" + violations=$((violations + 1)) + } + + # ── LICENSE ────────────────────────────────────────────────────── + # POSIX glob loop (not ls/find) so shellcheck stays happy and odd + # filenames are handled safely. Unmatched globs stay literal, so the + # `[ -e ]` test is false for them. + if [ "$REQUIRE_LICENSE" = "true" ]; then + license_found=no + for f in LICENSE LICENSE.* COPYING COPYING.*; do + if [ -e "$f" ]; then license_found=yes; break; fi + done + if [ "$license_found" = yes ]; then + echo "ok: LICENSE present" + else + note "No LICENSE/COPYING file at repo root (org standard: Apache-2.0)." + fi + fi + + # ── README ─────────────────────────────────────────────────────── + if [ ! -f README.md ]; then + note "No README.md at repo root." + else + bytes=$(wc -c < README.md | tr -d ' ') + if [ "$bytes" -lt "$README_MIN_BYTES" ]; then + note "README.md is a stub ($bytes bytes < $README_MIN_BYTES required)." + fi + if ! grep -qE '^[[:space:]]*(#[[:space:]]|')." + fi + # Count DISTINCT {{TOKEN}} occurrences, excluding the literal + # meta-example {{PLACEHOLDER}} (which docs legitimately mention). + # An unrendered template carries many distinct tokens + # ({{PROJECT_NAME}}, {{REPO}}, ...); a doc mentioning the syntax + # once should not trip. Threshold: 3 distinct tokens. + ph_count=$(grep -oE '\{\{[A-Z0-9_]+\}\}' README.md \ + | grep -vxF '{{PLACEHOLDER}}' | sort -u | wc -l | tr -d ' ') + if [ "$ph_count" -ge 3 ]; then + note "README.md still has $ph_count distinct {{PLACEHOLDER}} tokens (unrendered template?)." + fi + if grep -q 'ResQ README Template' README.md; then + note "README.md still contains the template scaffold marker comment." + fi + fi + + # ── Summary ────────────────────────────────────────────────────── + if [ "$violations" -eq 0 ]; then + echo "repo-standards: all checks passed." + exit 0 + fi + echo "repo-standards: $violations violation(s) found." + if [ "$STRICT" = "true" ]; then + echo "::error title=repo-standards::strict mode — failing on $violations violation(s)." + exit 1 + fi + echo "repo-standards: warn mode — not failing the build. Set strict:true to enforce." + exit 0 diff --git a/.github/workflows/required-gate.yml b/.github/workflows/required-gate.yml index 5e03adf..44fa12d 100644 --- a/.github/workflows/required-gate.yml +++ b/.github/workflows/required-gate.yml @@ -28,12 +28,27 @@ concurrency: cancel-in-progress: true jobs: + # Dogfood the org template/standards check on this repo itself. + repo-standards: + name: Repo standards + uses: ./.github/workflows/repo-standards.yml + required: name: required + needs: [repo-standards] + if: always() runs-on: ubuntu-latest steps: - name: Harden Runner uses: step-security/harden-runner@f808768d1510423e83855289c910610ca9b43176 # v2 with: egress-policy: audit - - run: echo "ok — .github repo has no language CI to gate on" + - name: Evaluate upstream results + env: + REPO_STANDARDS_RESULT: ${{ needs.repo-standards.result }} + run: | + set -eu + case "$REPO_STANDARDS_RESULT" in + success|skipped|"") echo "ok — .github repo has no language CI to gate on" ;; + *) echo "::error::repo-standards returned: $REPO_STANDARDS_RESULT"; exit 1 ;; + esac diff --git a/.github/workflows/required.yml b/.github/workflows/required.yml index ae1c8a9..d8b6a96 100644 --- a/.github/workflows/required.yml +++ b/.github/workflows/required.yml @@ -105,6 +105,15 @@ on: type: string required: false default: "" + repo-standards-strict: + description: > + Fail `required` when the repo violates template/standards + conformance (LICENSE present, non-stub README, no leftover + {{PLACEHOLDER}} tokens). Default warns only — flip to true once + the repo is clean. + type: boolean + required: false + default: false permissions: contents: read @@ -198,10 +207,17 @@ jobs: source-dir: ${{ inputs.cpp-source-dir }} cmake-flags: ${{ inputs.cpp-cmake-flags }} + # Template/standards conformance — lang-independent, runs for every repo. + repo-standards: + name: Repo standards + uses: ./.github/workflows/repo-standards.yml + with: + strict: ${{ inputs.repo-standards-strict }} + # `required` is the single status-check context consumed by Ruleset A. required: name: required - needs: [validate-lang, security, rust, python, node, dotnet, cpp] + needs: [validate-lang, security, rust, python, node, dotnet, cpp, repo-standards] if: always() runs-on: ubuntu-latest steps: @@ -218,6 +234,7 @@ jobs: NODE_RESULT: ${{ needs.node.result }} DOTNET_RESULT: ${{ needs.dotnet.result }} CPP_RESULT: ${{ needs.cpp.result }} + REPO_STANDARDS_RESULT: ${{ needs.repo-standards.result }} run: | set -eu # validate-lang must be success — typo defenses handled there @@ -226,7 +243,7 @@ jobs: exit 1 fi fail=0 - for r in "$SECURITY_RESULT" "$RUST_RESULT" "$PYTHON_RESULT" "$NODE_RESULT" "$DOTNET_RESULT" "$CPP_RESULT"; do + for r in "$SECURITY_RESULT" "$RUST_RESULT" "$PYTHON_RESULT" "$NODE_RESULT" "$DOTNET_RESULT" "$CPP_RESULT" "$REPO_STANDARDS_RESULT"; do case "$r" in success|skipped|"") ;; *) echo "::error::Upstream job returned: $r"; fail=1 ;; diff --git a/README.template.md b/README.template.md index 0265fc4..753e366 100644 --- a/README.template.md +++ b/README.template.md @@ -138,6 +138,27 @@ It {{CORE_VALUE_PROPOSITION}}. + + +### ResQ CLI + +Install the [`resq`](https://github.com/resq-software/crates) toolchain (and, +when run inside a repo, the canonical git hooks) in one line: + +```sh +curl -fsSL https://get.resq.software | sh +``` + +Prefer to read before piping to a shell: + +```sh +curl -fsSL https://get.resq.software -o install.sh +less install.sh +sh install.sh +``` + ### Node / Bun ```sh diff --git a/profile/README.md b/profile/README.md index c0b8816..d885f59 100644 --- a/profile/README.md +++ b/profile/README.md @@ -29,15 +29,21 @@ ResQ is a mission-critical autonomous platform for decentralized coordination in ## Get started -Install the `resq` CLI and onboard a cloned repo in two curls: +Install the `resq` CLI and onboard a repo in one line: ```bash -curl -fsSL https://raw.githubusercontent.com/resq-software/dev/main/scripts/install-resq.sh | sh -cd -curl -fsSL https://raw.githubusercontent.com/resq-software/dev/main/scripts/install-hooks.sh | sh +curl -fsSL https://get.resq.software | sh ``` -The first installs a SHA-verified `resq` binary (with a `cargo install --git` fallback). The second drops the canonical git hooks — copyright, secrets, polyglot format, audit — into the repo and offers a repo-aware `local-pre-push` scaffold. +This installs a SHA256-verified `resq` binary (with a `cargo install --git` fallback), optionally clones an org repo, and drops the canonical git hooks — copyright, secrets, polyglot format, audit — into it. + +Prefer to read before piping to a shell: + +```bash +curl -fsSL https://get.resq.software -o install.sh +less install.sh +sh install.sh +``` ## Links From 41e373b7af2f7e38247aff0e8eb4870e90634a1b Mon Sep 17 00:00:00 2001 From: Mike Odnis Date: Fri, 12 Jun 2026 02:26:17 -0400 Subject: [PATCH 2/3] docs(template): expand README template with Demo, Prerequisites, Security, Support, Acknowledgements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the per-repo README scaffold more complete and opinionated: - Demo: optional GIF/screenshot block with explicit dimensions (no CLS) and a live-demo link. - Prerequisites: runtime/version table pinned to what CI tests. - Security: coordinated-disclosure pointer to the org-inherited SECURITY.md — never file vulns as public issues. - Support: docs / SUPPORT.md / issue-chooser links. - Acknowledgements: optional attribution section. - Contributing: note that the single `required` status check (language CI + security scan + repo-standards) must stay green. - Table of Contents updated to match; all linked org files verified to exist (SECURITY.md, SUPPORT.md, CONTRIBUTING.md, LICENSE, banner). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.template.md | 75 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/README.template.md b/README.template.md index 753e366..e81a562 100644 --- a/README.template.md +++ b/README.template.md @@ -89,14 +89,19 @@ ## Table of Contents - [Overview](#overview) +- [Demo](#demo) - [Features](#features) +- [Prerequisites](#prerequisites) - [Install](#install) - [Quick Start](#quick-start) - [Usage](#usage) - [Configuration](#configuration) - [Contributing](#contributing) +- [Security](#security) +- [Support](#support) - [Changelog](#changelog) - [License](#license) +- [Acknowledgements](#acknowledgements) --- @@ -123,9 +128,28 @@ It {{CORE_VALUE_PROPOSITION}}. --- +## Demo + + + +

+ {{PROJECT_NAME}} demo +

+ +> **Try it live:** [{{LIVE_DEMO_URL}}]({{LIVE_DEMO_URL}}) · [Playground](https://resq.software) + +--- + ## Features - + - **{{FEATURE_1}}** — {{FEATURE_1_DESCRIPTION}} - **{{FEATURE_2}}** — {{FEATURE_2_DESCRIPTION}} @@ -133,6 +157,20 @@ It {{CORE_VALUE_PROPOSITION}}. --- +## Prerequisites + + + +| Requirement | Minimum | Notes | +|-------------|---------|-------| +| `{{RUNTIME}}` | `{{MIN_VERSION}}` | {{RUNTIME_NOTE}} | +| Platform | Linux / macOS / Windows | {{PLATFORM_NOTE}} | + +--- + ## Install + +- Built on the [ResQ platform](https://resq.software). +- {{ACKNOWLEDGEMENT_1}} + +--- + +

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

+ --- @@ -192,9 +205,9 @@ curl -fsSL https://get.resq.software | sh Prefer to read before piping to a shell: ```sh -curl -fsSL https://get.resq.software -o install.sh -less install.sh -sh install.sh +curl -fsSL https://get.resq.software -o install-resq.sh +less install-resq.sh +sh install-resq.sh ``` ### Node / Bun diff --git a/profile/README.md b/profile/README.md index d885f59..0efb8c2 100644 --- a/profile/README.md +++ b/profile/README.md @@ -40,9 +40,9 @@ This installs a SHA256-verified `resq` binary (with a `cargo install --git` fall Prefer to read before piping to a shell: ```bash -curl -fsSL https://get.resq.software -o install.sh -less install.sh -sh install.sh +curl -fsSL https://get.resq.software -o install-resq.sh +less install-resq.sh +sh install-resq.sh ``` ## Links