From 9e53bb63a35dfb904805347ab5b55cf321bcda91 Mon Sep 17 00:00:00 2001 From: Claudiu Schuster Date: Tue, 8 Sep 2026 16:19:07 +0200 Subject: [PATCH] Document active static publishing and the contributor entry points --- CONTRIBUTING.md | 4 ++++ README.md | 2 +- docs/README.md | 10 ++++++---- docs/hosting.md | 8 ++++++-- docs/ideas.md | 2 +- docs/release-automation.md | 25 ++++++++++++++++--------- docs/release-publication.md | 19 ++++++++++++++----- site/llms.txt | 2 ++ 8 files changed, 50 insertions(+), 22 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b4fdd4..71740f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,6 +4,8 @@ People and authorized software agents are welcome to improve OSS Singularity. On The [documentation map](docs/README.md) explains how the parts connect, links each task to its detailed contract, and provides a compact working loop for agents. +Merging an eligible static website change into protected `main` triggers production publication after the required checks. The [publication guide](docs/release-publication.md) explains eligibility, live verification and recovery. Commons Worker, database and static server policy changes have separate release gates. + ## Choose one small contribution - Correct an Atlas entry using official sources and the date you actually checked them. The [Atlas submission form](https://github.com/oss-singularity/website/issues/new?template=agent-submission.yml) also supports suggestions without a code change. @@ -47,6 +49,8 @@ python3 -m http.server --bind 127.0.0.1 --directory dist 4173 Open `http://127.0.0.1:4173/`. This serves the built pages but does not implement the Commons API. +The full publication tests also require OpenSSH's `ssh-keygen`. They generate temporary keys to check the real key-file parser; they install no keys and need no production credentials. + For Workshop/API journeys, use Node.js 24 after building `dist/`: ```sh diff --git a/README.md b/README.md index 7cfd196..dc8853d 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ The canonical address is `https://oss-singularity.io/`. Its `www` alias, the `.c See [docs/hosting.md](docs/hosting.md) for the verified baseline, safety boundaries, and acceptance gates. -The next infrastructure milestone is [release automation](docs/release-automation.md): a reviewed change should be publishable through the shared project workflow, with exact artifacts, scoped deployment access and recoverable failures. The [static artifact verifier](docs/release-artifacts.md), [GitHub rehearsal](docs/release-rehearsal.md), independent [candidate consumer](docs/release-candidates.md) and [required-check verifier](docs/release-checks.md) cover bytes, transport, completed-run handoff and CI provenance. Production promotion and recovery remain separate work. +Automatic [static publication](docs/release-publication.md) is enabled. Eligible changes merged into protected `main` publish after the exact commit passes its required checks, candidate verification and independent rebuild. The workflow verifies the live origin, CDN and API, and retains a rollback target. Changes to the deployed Commons source or static server policy require their separate release gates; [release automation](docs/release-automation.md) tracks the remaining Worker and database stages. Brand provenance and the current visual rules are recorded in [docs/brand-inputs.md](docs/brand-inputs.md). diff --git a/docs/README.md b/docs/README.md index 4d71977..36ed495 100644 --- a/docs/README.md +++ b/docs/README.md @@ -19,7 +19,8 @@ documents contain the detailed requirements and acceptance criteria. Build and test commands run from the repository root. The contributor guide owns the complete command list and tool requirements: Linux, Python 3.12 and GNU -utilities for the website checks; Node.js 24 for the Commons service tests. +utilities for the website checks, OpenSSH's `ssh-keygen` for publication tests, +and Node.js 24 for the Commons service tests. Normal development requires no package installation or production credentials. For a small context window, keep this map and one relevant feature contract at hand; load additional sections when the task or its checks require them. @@ -117,9 +118,10 @@ publication and recovery: | [Remote writer](release-static-remote.md) | Applying and recovering static file changes under an independently installed policy. | | [Static publication](release-publication.md) | Joining the candidate, checks, restricted endpoint and live verification; configuration, pilot and recovery requirements. | -Production activation still requires scoped credentials, the independently -installed endpoint and a successful canonical pilot. A passing fixture or -filesystem report is not a completed publication. +Automatic static publication is enabled for eligible changes merged into protected `main`. +The deployed Commons source and static server policy must remain compatible; +their changes require separate release gates. A passing fixture or filesystem +report alone is not a completed publication: inspect the workflow's live outcome. ## A compact working loop for agents diff --git a/docs/hosting.md b/docs/hosting.md index e974488..e330e2a 100644 --- a/docs/hosting.md +++ b/docs/hosting.md @@ -53,9 +53,13 @@ Namecheap's jailed shell exposes `/usr/local/cpanel/bin/uapi`, but the command c The source repository is published for transparent inspection and contribution. Repository policy keeps squash-only merges, branch cleanup, selected Actions, read-only workflow permissions, automated dependency updates, private vulnerability reporting, secret scanning with push protection, CodeQL, and a protected linear `main` branch with required repository checks. Public source does not widen the production credential or deployment boundary. -The OSS Singularity organization disables deploy keys across its repositories. A repo-specific cPanel deploy key was therefore not retained, no broader personal access token or account key was installed on the shared host, and no cPanel mirror was created. Authorized static releases use the verified operator SSH path after the protected merge and required checks. GitHub Actions validates source changes; automatic production deployment is not currently configured. Any future automation must transfer only the declared build output, serialize production deployments, verify the live result, and retain a rollback target. A repository-scoped GitHub App is reserved for a future requirement that genuinely needs server-initiated pulls; do not add its token-rotation and private-key machinery without that need. +The OSS Singularity organization disables GitHub deploy keys. The selected publication model pushes verified artifacts to the static origin; it needs no repository mirror or GitHub pull credential on the host. -The next infrastructure milestone is specified in [release automation](release-automation.md). It starts with portable, target-constrained release interfaces and a trusted post-merge dry run before enabling production workflows. Repository, environment and organization secrets require an explicit access design; the current operator credentials are not a CI deployment identity. +Automatic [static publication](release-publication.md) is enabled through the `production-static` environment, restricted to the `main` branch. Its separate SSH identity accepts only the installed fixed command, with pinned host identity and runtime. The scoped Cloudflare token permits this zone's cache purge and required reads. A read-only GitHub App supplies a temporary token restricted to this repository for the two policy reads unavailable to the built-in workflow token. Operator cPanel credentials and ordinary operator SSH access are not given to CI. + +The authenticated provider mapping, root identities, handler policy and preserved overlays were independently verified during installation and the canonical pilot. Routine publication checks those pinned target bindings together with the complete source payload, origin/edge responses, TLS, cache behavior and zone/DNS configuration. Provider layout or handler-policy changes require operator verification and an updated binding before routine publication resumes. + +The remaining infrastructure stages are specified in [release automation](release-automation.md). Worker and database promotion have separate credentials, compatibility and recovery requirements; the static workflow cannot update them. ## Available platform capabilities diff --git a/docs/ideas.md b/docs/ideas.md index be073e3..8a48146 100644 --- a/docs/ideas.md +++ b/docs/ideas.md @@ -14,7 +14,7 @@ An implementation is marked available only after its verification and release. | Visible operating costs and shared value | Participants should be able to understand revenue sources, agreed costs and distribution rules. | **Research.** See the historical architecture reference below and [optional settlement](coordination-roadmap.md#5-fair-compensation-and-optional-settlement--proposed). First use synthetic flows and explicit trust assumptions. | | Reputation grounded in inspectable work | Useful evidence should help assess contributions while making account-control and independence limits visible. | **Foundation exists; broader design open.** [Evidence reviews](../services/commons/README.md) attribute a review to an account, not a unique or independent person. Future signals need resistance to collusion, stale evidence and self-awarded authority. | | An easy home for contributors | Small improvements should be possible without private infrastructure access. | **Available.** [Contributor guide](../CONTRIBUTING.md), [local security testing](security-testing.md), reproducible checks and [bounded help requests](https://oss-singularity.io/help/) provide concrete starting points. | -| Publish through the shared project workflow | A reviewed improvement should reach production without depending on one maintainer's workstation or an assistant session. | **Next infrastructure milestone.** [Release automation](release-automation.md) starts with a portable, narrowly scoped release interface and a trusted dry run, then adds static publication and separate Worker/schema stages. Repository, environment and organization secrets must have explicit access boundaries. | +| Publish through the shared project workflow | A reviewed improvement should reach production without depending on one maintainer's workstation or an assistant session. | **Static publishing is enabled; Commons stages remain planned.** [Static publication](release-publication.md) verifies the canonical candidate, live result and retained rollback through constrained access. [Release automation](release-automation.md) tracks the separate Worker and database stages. | ## Historical architecture reference: Smart Mining diff --git a/docs/release-automation.md b/docs/release-automation.md index 0a9e382..5c61bf8 100644 --- a/docs/release-automation.md +++ b/docs/release-automation.md @@ -1,10 +1,9 @@ # Release automation -**Static publication is implemented; production activation is not complete.** The goal -is that an approved contribution can reach production through a reviewed PR, -successful checks and a reproducible release, without requiring Codex or one -maintainer's workstation. Routine promotion should become automatic once the -gates below have demonstrated reliable behavior. +**Automatic static publication is enabled.** Eligible contributions reach +production through a reviewed PR, successful checks and a reproducible release, +without requiring Codex or one maintainer's workstation. Separate Worker and +database promotion remain the next infrastructure stage. The offline [static artifact contract](release-artifacts.md) validates payload bytes and a constrained descriptor, including an independent rebuild comparison. @@ -22,8 +21,16 @@ engine behind a separate fixed command and static policy. Its registered private material has bounded, resumable retention while preserving the current rollback target. The [static publication client and workflow](release-publication.md) join these contracts with durable deployment intent, live acceptance and -conditional rollback. Scoped production access and a successful canonical pilot -remain required before enabling routine publication. +conditional rollback. Scoped production access and the canonical publication, +rollback and republication pilot are verified; see the +[pilot evidence](release-publication.md#pilot-reports-and-exceptional-recovery). + +| Stage | Current state | +| --- | --- | +| Constrained static adapter | Installed and verified with a separate restricted identity. | +| Trusted candidate and required checks | Canonical artifact transport, independent rebuild and exact protected-commit checks are active. | +| Static promotion | Enabled after publication, retained rollback and republication verification. | +| Worker and database promotion | Planned separately; static jobs cannot update either. | The target is exclusively OSS Singularity: its static destination, Commons Worker, dedicated D1 database and necessary cache invalidation. The existing @@ -75,8 +82,8 @@ journal, attempt-bound recovery and conditional rollback. Current product and historical integrity checks run before preparation. Fresh-process crash tests exercise both directions. The separate fixed-command observer can inspect an existing static installation. A separate restricted writer implements filesystem -operations with pinned server configuration and attempt-bound recovery; it is -not an enabled production publication workflow. +operations with pinned server configuration and attempt-bound recovery. The +publication workflow adds the source, live-verification and deployment-record gates. 1. **Portable, constrained adapter.** Extract a release interface without workstation paths or private historical state. Fix the permitted destinations diff --git a/docs/release-publication.md b/docs/release-publication.md index 7de057e..33cefb8 100644 --- a/docs/release-publication.md +++ b/docs/release-publication.md @@ -2,14 +2,14 @@ The [publication workflow](../.github/workflows/static-publication.yml) joins the existing candidate, required-check, filesystem and live-verification contracts. -**Activation is not complete.** A configured environment, restricted production -endpoint, scoped credentials and a successful canonical pilot are required -before enabling automatic runs. The Worker and database remain separate release -stages; this workflow cannot update either. +**Automatic static publication is enabled.** The protected environment, +restricted production endpoint and scoped credentials have passed a canonical +publication, retained rollback and republication pilot. The Worker and database +remain separate release stages; this workflow cannot update either. ## What a contributor can expect -Once enabled, successful repository checks on the current protected `main` +Successful repository checks on the current protected `main` trigger a static publication. The client independently verifies all required checks, including CodeQL, and consumes the single successful rehearsal for that same commit. A failed check, ambiguous run, changed artifact or newer `main` @@ -115,6 +115,15 @@ request. ## Pilot, reports and exceptional recovery +The initial pilot on 8 September 2026 verified a canonical +[plan](https://github.com/oss-singularity/website/actions/runs/34234743741), +[publication](https://github.com/oss-singularity/website/actions/runs/34235432795), +an operator-exercised retained rollback, and +[republication](https://github.com/oss-singularity/website/actions/runs/34236230540). +Independent provider checks confirmed preservation before and after each direction. +The pilot used unchanged page content to exercise release generations and +recovery; installed integration tests cover rollback of changed file preimages. + Dispatch `plan` on canonical `main` first. It runs the real candidate download, required-check, rebuild, baseline HTTP, API and edge-configuration checks. It does not prepare/apply a candidate, create a publication deployment or purge a diff --git a/site/llms.txt b/site/llms.txt index 79ab4fb..e378249 100644 --- a/site/llms.txt +++ b/site/llms.txt @@ -76,4 +76,6 @@ Pending proposals expire after 30 days; rejected proposals expire 30 days after - [Propose or correct an Atlas entry](https://github.com/oss-singularity/website/issues/new?template=agent-submission.yml): Human-reviewed GitHub issue. Never submit secrets or private data. - [Source and contribution guidelines](https://github.com/oss-singularity/website): Inspect and improve the home. +- [Documentation map](https://github.com/oss-singularity/website/blob/main/docs/README.md): Find the relevant architecture contract, source files and checks for a bounded change. +- [Contributing](https://github.com/oss-singularity/website/blob/main/CONTRIBUTING.md): Local setup and the contribution workflow. Eligible static website changes publish automatically after checks on protected `main`; Worker, database and static server policy changes have separate release gates. - [Security policy](https://github.com/oss-singularity/website/security/policy): Private vulnerability reporting.