diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 8d339b7..4714ad5 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,14 +1,4 @@ # SPDX-License-Identifier: MPL-2.0 -# CODEOWNERS - Define code review assignments -# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners -# -# Replace hyperpolymath with your GitHub username or team - -# Default owners for everything -* @hyperpolymath - -# Security-sensitive files require explicit review -SECURITY.md @hyperpolymath -.github/workflows/ @hyperpolymath -Trustfile.a2ml @hyperpolymath -.machine_readable/ @hyperpolymath +# Solo-maintained hyperpolymath repo: no owner lines by policy. +# See hyperpolymath/standards CODEOWNERS-POLICY.adoc (Rule 1). +# Sole-maintainer review is moot; SPDX headers carry attribution. diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index f83f2a5..9e51328 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -8,7 +8,7 @@ Replace all values: Patch Bridge - Your project name hyperpolymath - GitHub/GitLab username or org patch-bridge - Repository name - {{CONDUCT_EMAIL}} - Email for conduct reports + j.d.a.jewell@open.ac.uk - Email for conduct reports {{CONDUCT_TEAM}} - Name of conduct team/committee {{RESPONSE_TIME}} - Initial response SLA (e.g., 48 hours) 2026 - Current year @@ -136,7 +136,7 @@ If you experience or witness unacceptable behaviour, or have any other concerns, | Method | Details | Best For | |--------|---------|----------| -| **Email** | {{CONDUCT_EMAIL}} | Detailed reports, sensitive matters | +| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | | **Private Message** | Contact any maintainer directly | Quick questions, minor issues | | **Anonymous Form** | [Link to form if available] | When you need anonymity | @@ -231,7 +231,7 @@ For contributors with elevated access (Perimeter 2 or 1): If you believe an enforcement decision was made in error: 1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** {{CONDUCT_EMAIL}} with subject line "Appeal: [Original Report ID]" +2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" 3. **Explain** why you believe the decision should be reconsidered 4. **Provide** any new information not previously available @@ -310,8 +310,8 @@ We thank these communities for their leadership in creating welcoming spaces. If you have questions about this Code of Conduct: -- Open a [Discussion](https://{{FORGE}}/hyperpolymath/patch-bridge/discussions) (for general questions) -- Email {{CONDUCT_EMAIL}} (for private questions) +- Open a [Discussion](https://github.com/hyperpolymath/patch-bridge/discussions) (for general questions) +- Email j.d.a.jewell@open.ac.uk (for private questions) - Contact any maintainer directly --- diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 7c48f61..c6920e3 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,5 @@ # Clone the repository -git clone https://{{FORGE}}/hyperpolymath/patch-bridge.git +git clone https://github.com/hyperpolymath/patch-bridge.git cd patch-bridge # Using Nix (recommended for reproducibility) @@ -58,7 +58,7 @@ patch-bridge/ **Before reporting**: 1. Search existing issues -2. Check if it's already fixed in `{{MAIN_BRANCH}}` +2. Check if it's already fixed in `main` 3. Determine which perimeter the bug affects **When reporting**: @@ -91,10 +91,10 @@ Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) an Look for issues labelled: -- [`good first issue`](https://{{FORGE}}/hyperpolymath/patch-bridge/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://{{FORGE}}/hyperpolymath/patch-bridge/labels/help%20wanted) — Community help needed -- [`documentation`](https://{{FORGE}}/hyperpolymath/patch-bridge/labels/documentation) — Docs improvements -- [`perimeter-3`](https://{{FORGE}}/hyperpolymath/patch-bridge/labels/perimeter-3) — Community sandbox scope +- [`good first issue`](https://github.com/hyperpolymath/patch-bridge/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/patch-bridge/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/patch-bridge/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/patch-bridge/labels/perimeter-3) — Community sandbox scope --- diff --git a/.well-known/security.txt b/.well-known/security.txt index e5725f8..063097b 100644 --- a/.well-known/security.txt +++ b/.well-known/security.txt @@ -6,6 +6,6 @@ Contact: mailto:{{SECURITY_EMAIL}} Expires: 2026-12-31T23:59:59.000Z Encryption: {{PGP_KEY_URL}} Preferred-Languages: en -Canonical: https://{{FORGE}}/hyperpolymath/patch-bridge/.well-known/security.txt -Policy: https://{{FORGE}}/hyperpolymath/patch-bridge/blob/main/SECURITY.md +Canonical: https://github.com/hyperpolymath/patch-bridge/.well-known/security.txt +Policy: https://github.com/hyperpolymath/patch-bridge/blob/main/SECURITY.md Hiring: https://{{WEBSITE}}/careers diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 82905d4..ca6c712 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -44,3 +44,20 @@ Canonical project metadata belongs under `.machine_readable/`. 1. Read this file. 2. Read `.machine_readable/STATE.a2ml` and `.machine_readable/6a2/STATE.a2ml`. 3. Check the current audit report before modifying claims or release posture. + + + +## PRIORITY ACTION — this repository is not fully initialised + +35 substitution token(s) still have no value. **Read +`REQUIRES_INITIALISATION.md` in the repository root before doing anything +else here** — it lists every outstanding token, what it means, and which +files it belongs in. + +Do not fabricate values for them, and do not delete the sections that +contain them to quiet a gate. They are unfilled because they need a +decision, not because they were overlooked. Resolve what you legitimately +can, leave the rest, and delete `REQUIRES_INITIALISATION.md` only when +nothing outstanding remains. + + diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index c321dbe..e66f1f0 100644 --- a/QUICKSTART-MAINTAINER.adoc +++ b/QUICKSTART-MAINTAINER.adoc @@ -1,6 +1,6 @@ // SPDX-License-Identifier: CC-BY-SA-4.0 // Template: QUICKSTART-MAINTAINER.adoc — packaging, deploying, and maintaining -// Replace rsr-template-repo, {{PACKAGE_NAME}}, {{DEPS}} with actuals +// Replace rsr-template-repo, patch-bridge, {{DEPS}} with actuals = rsr-template-repo — Quick Start for Platform Maintainers :toc: :toclevels: 2 @@ -65,10 +65,10 @@ Files installed: | `$PREFIX/bin/` | Executables -| `$PREFIX/share/{{PACKAGE_NAME}}/` +| `$PREFIX/share/patch-bridge/` | Data files, assets -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` +| `$PREFIX/share/doc/patch-bridge/` | Documentation | `$PREFIX/share/applications/` @@ -80,9 +80,9 @@ Files installed: == Configuration -Default config location: `$XDG_CONFIG_HOME/{{PACKAGE_NAME}}/config.toml` +Default config location: `$XDG_CONFIG_HOME/patch-bridge/config.toml` -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` +Fallback: `$HOME/.config/patch-bridge/config.toml` == Health Checks @@ -102,7 +102,7 @@ just build-release just install --prefix=/usr/local ---- -Or via OPSM: `opsm update {{PACKAGE_NAME}}` +Or via OPSM: `opsm update patch-bridge` == Security Notes @@ -117,8 +117,8 @@ For deploying multiple instances (e.g., different users or tenants): [source,bash] ---- -just install --prefix=/opt/{{PACKAGE_NAME}}-instance1 --config=/etc/{{PACKAGE_NAME}}/instance1.toml -just install --prefix=/opt/{{PACKAGE_NAME}}-instance2 --config=/etc/{{PACKAGE_NAME}}/instance2.toml +just install --prefix=/opt/patch-bridge-instance1 --config=/etc/patch-bridge/instance1.toml +just install --prefix=/opt/patch-bridge-instance2 --config=/etc/patch-bridge/instance2.toml ---- Each instance has isolated config, data, and logs. diff --git a/REQUIRES_INITIALISATION.md b/REQUIRES_INITIALISATION.md new file mode 100644 index 0000000..71a1d2a --- /dev/null +++ b/REQUIRES_INITIALISATION.md @@ -0,0 +1,343 @@ + + +# REQUIRES INITIALISATION + +**This repository is not finished being set up.** 35 substitution token(s) across 21 file(s) still have no value. + +## Why this is not already done + +This repo was created from `hyperpolymath/rsr-template-repo`. The mint +(`just repo-init`) fills every token that has a single mechanical answer — +owner, repo, author, dates, licence, branch — and it has done so here. + +The tokens below are the ones it *deliberately cannot* answer. They need a +decision or a fact that exists only in your head: what this project is for, +what command builds it, which port the service listens on, whether a PGP key +is held at all. The template's own token vocabulary says as much — you cannot +sensibly answer "required invariants" in a thirty-second bootstrap. + +They were left **visibly unfilled on purpose**. The alternatives were both +worse: inventing plausible values would put confident falsehoods into a +security policy and an architecture document, and silently deleting the +sections would hide the fact that a decision is owed. A visible gap is +honest; a fabricated answer is not. + +## Do not delete this file until every item below is resolved + +This file is the only marker that the work is outstanding. Deleting it early +does not finish the setup, it just conceals it — and the next person or agent +to arrive will reasonably assume the repo is complete. + +- **If you are a person:** delete this file yourself once the last item is done. +- **If you are an agent:** resolve what you legitimately can, leave the rest, + and delete this file only when no token below remains anywhere in the tree. + Do not delete it to make a gate go green. + +Re-running the estate top-up tool will remove this file automatically once +nothing is outstanding, so the safest way to finish is to fix the tokens and +let the check confirm it. + +## Do these first + +`.github/settings.yml` is applied to the forge by a GitHub App. An +unfilled token here can be written into the repository's real name or +description. This has fired before in this estate: illegal braces were +collapsed to dashes and a repo was renamed `-REPO-`, which then read as +deleted. + +- `{{DESCRIPTION}}` — One-line description used in .github/settings.yml. HIGH PRIORITY: settings.yml is applied by a GitHub App, so an unfilled token here can be written into forge metadata verbatim. + +## What is needed, and where it goes + +### `{{AUTHOR_EMAIL_ALT}}` + +Appears in: + +- `.github/.mailmap` + +### `{{AUTHOR_ORG}}` + +Author's organisation. NOTE: no filled instance of this exists anywhere in the estate — consider deleting the field instead. + +Appears in: + +- `.machine_readable/svc/k9/examples/project-metadata.k9.ncl` + +### `{{BUILD_CMD}}` + +The exact command that builds this project. + +Appears in: + +- `QUICKSTART-DEV.adoc` + +### `{{BUILD_OUTPUT_PATH}}` + +Where the build artefact lands. + +Appears in: + +- `QUICKSTART-MAINTAINER.adoc` + +### `{{COMPONENT}}` + +Appears in: + +- `TOPOLOGY.md` + +### `{{CONDUCT_TEAM}}` + +Name of the conduct body. If there is no committee, rewrite the sentence rather than substituting a plural noun into 'a {{CONDUCT_TEAM}} member'. + +Appears in: + +- `.github/CODE_OF_CONDUCT.md` + +### `{{CONSUMER1}}` + +A downstream repo that consumes this one. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{CONSUMER2}}` + +A second downstream consumer. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{DEP1}}` + +First named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{DEP2}}` + +Second named dependency, in .machine_readable/INTENT.contractile. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{DEPS}}` + +Prose summary of runtime/build dependencies. + +Appears in: + +- `QUICKSTART-MAINTAINER.adoc` + +### `{{DESCRIPTION}}` + +One-line description used in .github/settings.yml. HIGH PRIORITY: settings.yml is applied by a GitHub App, so an unfilled token here can be written into forge metadata verbatim. + +Appears in: + +- `.github/settings.yml` + +### `{{DOWNSTREAM_CONSUMERS}}` + +Appears in: + +- `TOPOLOGY.md` + +### `{{LANGUAGE}}` + +Appears in: + +- `TOPOLOGY.md` + +### `{{LANG_STACK}}` + +The language stack, in prose. + +Appears in: + +- `QUICKSTART-DEV.adoc` + +### `{{LICENSE}}` + +SPDX identifier for this repo's licence. + +Appears in: + +- `container/Containerfile` +- `container/manifest.toml` +- `docs/developer/ABI-FFI-README.adoc` + +### `{{MONOREPO_OR_STANDALONE}}` + +Literally 'monorepo' or 'standalone'. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{MUST_INVARIANTS}}` + +The invariants this project guarantees. Not answerable in a bootstrap; it is the point of the repo. + +Appears in: + +- `QUICKSTART-DEV.adoc` + +### `{{ONE_PARAGRAPH_ANTI_PURPOSE}}` + +A paragraph on what this deliberately is NOT for. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{ONE_PARAGRAPH_PURPOSE}}` + +A paragraph on what this is for. + +Appears in: + +- `.machine_readable/INTENT.contractile` + +### `{{PGP_KEY_URL}}` + +Public URL the PGP key can be fetched from. Same caveat as PGP_FINGERPRINT. + +Appears in: + +- `.well-known/security.txt` + +### `{{PORT}}` + +Port the container service listens on. + +Appears in: + +- `container/Containerfile` +- `container/compose.toml` +- `container/deploy.k9.ncl` +- `container/entrypoint.sh` +- `container/manifest.toml` +- `container/vordr.toml` + +### `{{PROJECT_DOMAIN}}` + +Taxonomy value for the subject domain. + +Appears in: + +- `.machine_readable/anchors/ANCHOR.a2ml` + +### `{{PROJECT_KIND}}` + +Taxonomy value (library, service, tool, lab…). + +Appears in: + +- `.machine_readable/anchors/ANCHOR.a2ml` + +### `{{PROJECT_PURPOSE}}` + +One line: what this exists to do. + +Appears in: + +- `.machine_readable/anchors/ANCHOR.a2ml` +- `guix.scm` + +### `{{PROJECT_UNIQUE_STRENGTH}}` + +What this does that its alternatives do not. + +Appears in: + +- `.machine_readable/agent_instructions/methodology.a2ml` + +### `{{PURPOSE}}` + +Appears in: + +- `TOPOLOGY.md` + +### `{{REGISTRY}}` + +Container registry to publish to. + +Appears in: + +- `container/compose.toml` +- `container/ct-build.sh` +- `container/deploy.k9.ncl` + +### `{{RESPONSE_TIME}}` + +Initial-response SLA for a security or conduct report. Promise only what a solo maintainer can actually meet. + +Appears in: + +- `.github/CODE_OF_CONDUCT.md` + +### `{{SECURITY_EMAIL}}` + +Address for private vulnerability reports. Two competing values exist in the estate (`6759885+hyperpolymath@users.noreply.github.com` and `security@hyperpolymath.org`) — pick one deliberately. + +Appears in: + +- `.well-known/security.txt` + +### `{{SERVICE_NAME}}` + +Container service name. + +Appears in: + +- `container/.gatekeeper.yaml` +- `container/Containerfile` +- `container/compose.toml` +- `container/ct-build.sh` +- `container/deploy.k9.ncl` +- `container/entrypoint.sh` +- `container/manifest.toml` +- `container/vordr.toml` + +### `{{TEST_CMD}}` + +The exact command that runs its tests. + +Appears in: + +- `QUICKSTART-DEV.adoc` + +### `{{UPSTREAM_DEPS}}` + +Appears in: + +- `TOPOLOGY.md` + +### `{{VERSION}}` + +Version/tag for the container image. + +Appears in: + +- `container/deploy.k9.ncl` +- `container/manifest.toml` +- `container/vordr.toml` + +### `{{WEBSITE}}` + +Project homepage URL, or delete the field if there is none. + +Appears in: + +- `.well-known/security.txt` + +--- + +Generated by the estate top-up pass. Rationale and the governing rulings are +in `hyperpolymath/standards`; the token vocabulary is +`.machine_readable/ai/PLACEHOLDERS.adoc` in `rsr-template-repo`. diff --git a/container/Containerfile b/container/Containerfile index 58a10a2..b6db258 100644 --- a/container/Containerfile +++ b/container/Containerfile @@ -71,8 +71,8 @@ FROM cgr.dev/chainguard/wolfi-base:latest # OCI image labels (compatible with cerro-torre .ctp bundle metadata) LABEL org.opencontainers.image.title="Patch Bridge" \ org.opencontainers.image.description="CVE-mitigation design and extraction target from panic-attacker" \ - org.opencontainers.image.url="https://{{FORGE}}/hyperpolymath/patch-bridge" \ - org.opencontainers.image.source="https://{{FORGE}}/hyperpolymath/patch-bridge" \ + org.opencontainers.image.url="https://github.com/hyperpolymath/patch-bridge" \ + org.opencontainers.image.source="https://github.com/hyperpolymath/patch-bridge" \ org.opencontainers.image.vendor="hyperpolymath" \ org.opencontainers.image.licenses="{{LICENSE}}" \ org.opencontainers.image.authors="Jonathan D.A. Jewell " \ diff --git a/container/manifest.toml b/container/manifest.toml index 4212a2b..21fefda 100644 --- a/container/manifest.toml +++ b/container/manifest.toml @@ -16,11 +16,11 @@ cerro-torre .ctp bundle with Ed25519 signing and full provenance tracking. """ license = "{{LICENSE}}" -homepage = "https://{{FORGE}}/hyperpolymath/patch-bridge" -maintainer = "Jonathan D.A. Jewell <{{EMAIL}}>" +homepage = "https://github.com/hyperpolymath/patch-bridge" +maintainer = "Jonathan D.A. Jewell " [provenance] -upstream = "https://{{FORGE}}/hyperpolymath/patch-bridge" +upstream = "https://github.com/hyperpolymath/patch-bridge" import_date = 2026-04-13T00:00:00Z [dependencies] diff --git a/container/vordr.toml b/container/vordr.toml index 8349209..39dba62 100644 --- a/container/vordr.toml +++ b/container/vordr.toml @@ -94,7 +94,7 @@ output = "stdout" # on = ["failure", "recovery", "resource_critical"] # [notifications.email] -# to = "{{EMAIL}}" +# to = "j.d.a.jewell@open.ac.uk" # from = "vordr@{{SERVICE_NAME}}.local" # smtp = "smtp://localhost:25" # on = ["failure", "resource_critical"] diff --git a/docs/architecture/THREAT-MODEL.adoc b/docs/architecture/THREAT-MODEL.adoc index 4666a3c..0aaabb2 100644 --- a/docs/architecture/THREAT-MODEL.adoc +++ b/docs/architecture/THREAT-MODEL.adoc @@ -10,7 +10,7 @@ |---------------|--------------------------------| | Project | Patch Bridge | | Version | 1.0 | -| Last Reviewed | {{DATE}} | +| Last Reviewed | 2026-08-05 | | Author | Jonathan D.A. Jewell | | Methodology | STRIDE | diff --git a/docs/attribution/CITATION.cff b/docs/attribution/CITATION.cff index c987ed1..d92de04 100644 --- a/docs/attribution/CITATION.cff +++ b/docs/attribution/CITATION.cff @@ -1,14 +1,14 @@ cff-version: 1.2.0 message: "If you use this software, please cite it as below." authors: -- family-names: "{{AUTHOR_LAST}}" - given-names: "{{AUTHOR_FIRST}}" +- family-names: "Jewell" + given-names: "Jonathan" orcid: "https://orcid.org/0000-0000-0000-0000" # Placeholder title: "Patch Bridge" version: 0.1.0 date-released: 2026-04-13 -url: "https://{{FORGE}}/hyperpolymath/patch-bridge" -repository-code: "https://{{FORGE}}/hyperpolymath/patch-bridge" +url: "https://github.com/hyperpolymath/patch-bridge" +repository-code: "https://github.com/hyperpolymath/patch-bridge" license: MPL-2.0 keywords: - "rsr" diff --git a/docs/attribution/CITATIONS.adoc b/docs/attribution/CITATIONS.adoc index bcbd096..a9a446a 100644 --- a/docs/attribution/CITATIONS.adoc +++ b/docs/attribution/CITATIONS.adoc @@ -6,7 +6,7 @@ [source,bibtex] ---- @software{Patch Bridge_2026, - author = {{{AUTHOR_LAST}}, {{AUTHOR_FIRST}}}, + author = {Jewell, Jonathan}, title = {Patch Bridge}, year = {2026}, url = {https://github.com/hyperpolymath/Patch Bridge}, @@ -16,7 +16,7 @@ == Harvard Style -{{AUTHOR_LAST}}, {{AUTHOR_INITIALS}} (2026) _Patch Bridge_ [Computer software]. Available at: https://github.com/hyperpolymath/Patch Bridge +Jewell, JDJ (2026) _Patch Bridge_ [Computer software]. Available at: https://github.com/hyperpolymath/Patch Bridge == OSCOLA @@ -24,11 +24,11 @@ Jonathan D.A. Jewell, 'Patch Bridge' (2026)