Skip to content

Commit 21416cd

Browse files
feat(rsr): scaffold lifecycle canon, archetype presets, oracle-aligned profile checker (#515)
## What The normative half of the once-and-for-all scaffolding resolution (companion: rsr-template-repo PR #2, ADR-0003). - **`spec/SCAFFOLD-LIFECYCLE.adoc`** — the lifecycle canon: Forge (mint → provision → configure → harness) with per-stage MUST exit criteria, Sustain (corrective / adaptive / perfective / preventive) with the owning tool for each, the roles table (canon / spine / composer / oracle / fleet), the provenance requirement (the estate's Copier-answer-file equivalent, in the ADR-0002 contract shape), and autonomy boundaries (unattended read-only vs owner-gated mutation vs never-automated). - **`template-capability-gates.toml` 0.1.0 → 0.2.0** (additive MINOR per its own versioning rules): new capability `plugin`; presets `julia-library`, `wordpress-plugin`, `zotero-plugin`, `userscript`. - **`check-rsr-profile.sh`** — now accepts the `[rsr-profile]` section name and multi-line capability arrays. The normative oracle (hypatia `RsrConformance.load_capabilities/1`) accepts both; the reference checker was stricter than the oracle and errored on the very profile rsr-template-repo ships. Canary-tested: template profile parses (real findings now reported), undeclared profile still exits 2, preset form resolves. - **`REPO-STANDARD-MUST-INTEND-LIKE.adoc`** relocated from rsr-julia-library-template-repo (explicitly language-agnostic; was misfiled in the Julia variant). Variant-side retirement is a follow-up there. ## Honest findings surfaced (not fixed here) Running the fixed checker against rsr-template-repo reports 5 genuine profile↔tree mismatches (e.g. `Containerfile` at root missing while `container` declared, `release.yml` present without `published-package`). Pre-existing template debt, now visible instead of hidden behind a parse error. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 parent 8813ecf commit 21416cd

4 files changed

Lines changed: 470 additions & 6 deletions

File tree

.machine_readable/template-capability-gates.toml

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,16 @@
1010
# Arrays are kept single-line so the checker can parse them with grep.
1111

1212
[meta]
13-
version = "0.1.0"
13+
version = "0.2.0"
1414
policy = "TEMPLATE-APPLICABILITY-POLICY.adoc"
1515

1616
[capabilities]
1717
# Every capability a profile may declare.
18-
known = ["rust", "zig", "agda", "idris2", "haskell", "gleam", "elixir", "affinescript", "julia", "ocaml", "bash", "cli", "library", "ffi", "abi", "api-service", "formal-proofs", "mobile", "web-ui", "docs-site", "published-package", "container", "reproducible-build", "governance-tier", "benchmarks"]
18+
# "plugin" = code hosted inside a third-party extension host (WordPress,
19+
# Zotero, a userscript manager): the host owns the runtime and the packaging
20+
# rules, so host-mandated files are exempt from the usual language gates the
21+
# way interop-target bindings are.
22+
known = ["rust", "zig", "agda", "idris2", "haskell", "gleam", "elixir", "affinescript", "julia", "ocaml", "bash", "cli", "library", "ffi", "abi", "api-service", "formal-proofs", "mobile", "web-ui", "docs-site", "published-package", "container", "reproducible-build", "governance-tier", "benchmarks", "plugin"]
1923

2024
[baseline]
2125
# Always carried (gate = empty). Globs/dirs allowed; not capability-gated.
@@ -55,3 +59,9 @@ rust-service = ["rust", "api-service", "container", "reproducible-build"]
5559
formal-proof-lib = ["formal-proofs", "library"]
5660
docs-site = ["docs-site"]
5761
affinescript-app = ["affinescript", "web-ui"]
62+
# Archetype presets (rsr-template-repo archetypes/ carry the matching name;
63+
# see spec/SCAFFOLD-LIFECYCLE.adoc and rsr-template-repo ADR-0003).
64+
julia-library = ["julia", "library", "docs-site", "published-package"]
65+
wordpress-plugin = ["plugin", "web-ui"]
66+
zotero-plugin = ["plugin"]
67+
userscript = ["plugin"]
Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
// SPDX-License-Identifier: CC-BY-SA-4.0
2+
// Relocated 2026-07-21 from rsr-julia-library-template-repo (its VARIANT.a2ml
3+
// lists it under paths.added). The document is explicitly language-agnostic
4+
// and belongs in the canon; the variant-side copy is retired separately.
5+
= Universal Repo Standard (Must / Intend / Like)
6+
7+
This document is designed as a reusable baseline for *every* repository (Julia and non-Julia).
8+
It combines dependability, security, accessibility, interoperability, functionality, performance,
9+
and data/information governance into one operational standard.
10+
11+
Use this as:
12+
13+
* A repo bootstrap checklist
14+
* A release-readiness checklist
15+
* A policy reference for CI/CD gates
16+
17+
== Top-Level Principles (Apply To Every Repo)
18+
19+
1. Dependability: deterministic behavior, graceful failure, and observable recovery.
20+
2. Security: secure-by-default design, supply-chain integrity, least privilege.
21+
3. Accessibility: inclusive UX and docs, equivalent access to critical workflows.
22+
4. Interoperability: stable contracts, versioned interfaces, compatibility guarantees.
23+
5. Functionality: features are complete, correct, and match documented claims.
24+
6. Performance: measurable baselines, regression protection, explicit budgets.
25+
7. Data/Information Governance: data classification, minimization, lineage, retention, and deletion controls.
26+
27+
== Minimum Files In Every Repo
28+
29+
Must include:
30+
31+
* `README` (what it does, supported scope, quickstart, known limits)
32+
* `ROADMAP` (Must/Intend/Like or equivalent staged plan)
33+
* `CHANGELOG` (user-visible changes and migration impact)
34+
* `SECURITY.md` (reporting + hardening posture)
35+
* `LICENSE`
36+
* `CONTRIBUTING` (workflow and quality gates)
37+
* `CODEOWNERS` or `MAINTAINERS`
38+
* CI workflow(s) for test + lint + dependency/security checks
39+
* Reproducible dependency lock strategy (language-specific)
40+
* Operational runbook or `docs/ops` for incident response
41+
42+
== MUST (Non-Negotiable Baseline)
43+
44+
=== Dependability
45+
46+
* No silent corruption or "fake" token values for critical outputs.
47+
* Explicit failure modes and fallback policy per critical path.
48+
* Health checks and structured diagnostics for runtime paths.
49+
* Fault counters (errors, fallbacks, recoveries) with alert thresholds.
50+
* Deterministic CI tests for happy path + failure path + fallback behavior.
51+
52+
=== Security
53+
54+
* Threat model exists and is reviewed periodically.
55+
* Secrets never committed; managed via secure runtime secret injection.
56+
* Dependency scanning + SAST + license checks in CI.
57+
* Signed releases/artifacts where supported.
58+
* Principle of least privilege for CI, runtime identities, and tokens.
59+
60+
=== Containers And Images (High-Security Ready)
61+
62+
* Pinned base images by digest; avoid floating tags in production.
63+
* Non-root runtime user; read-only root filesystem when possible.
64+
* Drop unnecessary Linux capabilities; avoid privileged containers.
65+
* SBOM generation + vulnerability scanning + policy gate.
66+
* Image signing and provenance attestation in release pipeline.
67+
* Explicit runtime constraints (seccomp/AppArmor/SELinux as applicable).
68+
69+
=== Interoperability And API Contracts
70+
71+
* Versioned API/ABI contracts with compatibility expectations.
72+
* Contract tests for REST/gRPC/GraphQL/FFI boundaries.
73+
* Backward-compatibility policy and deprecation lifecycle.
74+
* Clear error taxonomy (retryable vs non-retryable) and status semantics.
75+
76+
=== Functionality And Correctness
77+
78+
* Documentation claims must match tested behavior.
79+
* Acceptance tests for each "shipped" feature claim.
80+
* No unresolved critical work markers in production code paths.
81+
* Release checklist gates must pass before merge/release.
82+
83+
=== Performance
84+
85+
* Baseline benchmarks for critical operations and key backends.
86+
* Regression thresholds enforced in CI where baselines exist.
87+
* Performance evidence artifacts retained from CI runs.
88+
* Resource budgets (latency, memory, CPU, I/O) defined for critical flows.
89+
90+
=== Data/Information Governance
91+
92+
* Data classification policy (public/internal/confidential/restricted).
93+
* Data minimization and purpose limitation documented.
94+
* Retention and deletion policy documented and testable.
95+
* Audit trails for critical decisions and transformations.
96+
* Encryption requirements for data at rest/in transit documented.
97+
98+
=== Accessibility
99+
100+
* User-facing interfaces meet baseline accessibility criteria.
101+
* Docs include plain-language quickstarts and operational troubleshooting.
102+
* Keyboard-only and screen-reader considerations for web UI repos.
103+
104+
== INTEND (Planned, High-Value Next Layer)
105+
106+
=== Dependability
107+
108+
* Circuit breakers and adaptive retry with backoff/jitter.
109+
* Chaos/fault-injection tests in non-production environments.
110+
* Automatic quarantine of persistently failing backends/providers.
111+
* Error budget policy tied to SLOs.
112+
113+
=== Security
114+
115+
* Mandatory security review for high-impact changes.
116+
* Ephemeral credentials and workload identity adoption.
117+
* Continuous policy-as-code validation (admission controls, OPA, etc.).
118+
* Signed commits/tags and stricter branch protection.
119+
120+
=== Containers/Runtime
121+
122+
* Distroless/minimal images for production workloads.
123+
* Runtime sandboxing for untrusted workloads.
124+
* Dedicated hardened node pools for sensitive workloads.
125+
* Provenance verification at deploy time.
126+
127+
=== Interoperability
128+
129+
* Multi-version compatibility test matrix (N-1, N, N+1 where applicable).
130+
* Golden test vectors for serialization/protocol compatibility.
131+
* SDK/client conformance tests against reference server behavior.
132+
133+
=== Functionality
134+
135+
* Formalized "definition of done" templates by feature type.
136+
* Auto-generated API docs from source contracts.
137+
* Domain-specific invariants/property tests.
138+
139+
=== Performance
140+
141+
* Automated trend dashboards with release-over-release comparisons.
142+
* Capacity modeling and saturation testing.
143+
* Hardware-specific tuning profiles validated by CI evidence.
144+
145+
=== Data Governance
146+
147+
* Data lineage map and classification tagging automation.
148+
* Policy checks that block non-compliant schema/data changes.
149+
* Differential privacy/redaction controls where needed.
150+
151+
=== Accessibility
152+
153+
* Automated accessibility checks in CI for UI repos.
154+
* Accessibility issue triage and SLA policy.
155+
156+
== LIKE (Aspirational Or Context-Dependent)
157+
158+
* Formal verification for high-assurance modules.
159+
* Multi-region active-active resilience for critical services.
160+
* Reproducible builds with full hermetic toolchains.
161+
* Runtime self-optimization under strict safety guards.
162+
* Advanced provenance federation across polyrepo ecosystems.
163+
* Organizational scorecards across all principles per repo.
164+
165+
== Suggested CI Gates (Portable Template)
166+
167+
Must gates:
168+
169+
* Build + unit/integration tests
170+
* Contract tests (APIs/ABI/FFI)
171+
* Failure-mode and fallback tests
172+
* Lint/style/static checks
173+
* Vulnerability + license scans
174+
* Performance regression checks (where baseline exists)
175+
* Documentation claim alignment checks
176+
177+
Evidence artifacts:
178+
179+
* Test results
180+
* Security scan reports
181+
* Benchmark/performance evidence
182+
* Capability/diagnostic snapshots
183+
* SBOM + provenance attestations (release)
184+
185+
== Practical Scope Control (To Avoid "Infinite Work")
186+
187+
Apply this in tiers:
188+
189+
1. Tier 1 (immediate): production-critical paths and externally exposed interfaces.
190+
2. Tier 2 (next): high-usage internal paths and integration boundaries.
191+
3. Tier 3 (later): low-risk or experimental components.
192+
193+
Do not block all progress on full perfection. Gate by risk and blast radius.
194+
195+
== Policy On Fallback Values
196+
197+
For critical computation and security-sensitive flows:
198+
199+
* Do not substitute dummy/token values silently.
200+
* Prefer: retry -> alternate backend/path -> explicit failure.
201+
* Every recovery or degradation event must be observable.
202+
203+
For non-critical optional fields:
204+
205+
* Defaults are acceptable only with clear provenance and policy.
206+
207+
== How To Reuse In Other Repos
208+
209+
Copy this file and then customize:
210+
211+
* Language-specific tooling sections
212+
* API and data governance specifics
213+
* Backend matrix and performance budgets
214+
* Regulatory/compliance requirements
215+
216+
Keep the principle set and Must baseline intact unless a stronger control replaces it.

0 commit comments

Comments
 (0)