diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 7f60a0c..4714ad5 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,9 +1,4 @@ -# Code Owners - -# Default: All contributors with write access are code owners -* @metadatastician - -# For specific paths, add explicit owners below -# Example: -# /src/* @team-lead -# /docs/* @docs-maintainer +# SPDX-License-Identifier: MPL-2.0 +# 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/.machine_readable/agent_instructions/methodology.a2ml b/.machine_readable/agent_instructions/methodology.a2ml index 754f357..33f4679 100644 --- a/.machine_readable/agent_instructions/methodology.a2ml +++ b/.machine_readable/agent_instructions/methodology.a2ml @@ -101,7 +101,7 @@ constraints = [ # These rules detect corrupt/template/stale state files. [methodology.state-validation] -reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"] +reject-if-contains = ["{{PLACEHOLDER}}", "INTSOC_TRANSACTOR", "rsr-template-repo"] reject-if-project-name-mismatch = true staleness-threshold-days = 90 fallback-files = ["TODO.md", "TODO.adoc", "ROADMAP.adoc", "README.adoc"] diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 3bb68db..37858fa 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -129,3 +129,20 @@ intsoc-transactor/ - **Maintained By:** Jonathan D.A. Jewell (hyperpolymath) - **License:** MPL-2.0 - **Protocol:** https://github.com/hyperpolymath/0-ai-gatekeeper-protocol + + + +## PRIORITY ACTION — this repository is not fully initialised + +39 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/PLACEHOLDERS.md b/PLACEHOLDERS.md index 2c284ce..2e3ab51 100644 --- a/PLACEHOLDERS.md +++ b/PLACEHOLDERS.md @@ -21,7 +21,7 @@ sed -i 's/Jonathan D.A. Jewell/Jane Doe/g' $(grep -rl 'Jonathan D.A. Jewell' .) sed -i 's/j.d.a.jewell@open.ac.uk/jane@example.org/g' $(grep -rl 'j.d.a.jewell@open.ac.uk' .) sed -i 's/hyperpolymath/my-org/g' $(grep -rl 'hyperpolymath' .) sed -i 's/Intsoc Transactor/my-project/g' $(grep -rl 'Intsoc Transactor' .) -sed -i 's/{{PROJECT}}/MY_PROJECT/g' $(grep -rl '{{PROJECT}}' .) +sed -i 's/INTSOC_TRANSACTOR/MY_PROJECT/g' $(grep -rl 'INTSOC_TRANSACTOR' .) sed -i 's/{{project}}/my_project/g' $(grep -rl '{{project}}' .) sed -i 's/intsoc-transactor/my-project/g' $(grep -rl 'intsoc-transactor' .) sed -i 's/github.com/github.com/g' $(grep -rl 'github.com' .) @@ -39,9 +39,9 @@ sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) | `j.d.a.jewell@open.ac.uk` | Primary contact email | `jane@example.org` | SPDX headers (all files), .mailmap, .reuse/dep5, .well-known/humans.txt | | `{{AUTHOR_EMAIL_ALT}}` | Previous/secondary email (for .mailmap) | `old@example.com` | .mailmap | | `{{AUTHOR_ORG}}` | Author's organization/affiliation | `Acme University` | project-metadata.k9.ncl | -| `{{AUTHOR_LAST}}` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | -| `{{AUTHOR_FIRST}}` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | -| `{{AUTHOR_INITIALS}}` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | +| `Jewell` | Author surname (for citations) | `Doe` | docs/CITATIONS.adoc | +| `Jonathan` | Author first name (for citations) | `Jane` | docs/CITATIONS.adoc | +| `JDJ` | Author initials (for citations) | `J.` | docs/CITATIONS.adoc | ### Project Identity @@ -49,7 +49,7 @@ sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) |---|---|---|---| | `Intsoc Transactor` | Human-readable project name | `My Project` | SECURITY.md, CODE_OF_CONDUCT.md, TOPOLOGY.md, STATE.a2ml, Justfile, GOVERNANCE.md, MAINTAINERS.md, flake.nix, devcontainer.json | | `{{PROJECT_DESCRIPTION}}` | One-line description | `A tool for X` | flake.nix | -| `{{PROJECT}}` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | +| `INTSOC_TRANSACTOR` | Uppercase identifier (for Idris2 modules, C macros) | `MY_PROJECT` | ABI-FFI-README.md, src/abi/*.idr, ffi/zig/*.zig | | `{{project}}` | Lowercase identifier (for C symbols, filenames) | `my_project` | ABI-FFI-README.md, ffi/zig/*.zig | | `intsoc-transactor` | Repository name (slug) | `my-project` | CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, cliff.toml | | `hyperpolymath` | GitHub/GitLab org or username | `my-org` | SPDX headers, CONTRIBUTING.md, SECURITY.md, GOVERNANCE.md, MAINTAINERS.md, CODEOWNERS, mirror.yml, cliff.toml | @@ -61,7 +61,7 @@ sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) |---|---|---|---| | `2026` | Current year | `2026` | SPDX headers (all files), GOVERNANCE.md, MAINTAINERS.md | | `2026-03-16` | Current date (ISO) | `2026-02-14` | STATE.a2ml, MAINTAINERS.md | -| `{{DATE}}` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | +| `2026-08-05` | Last updated date | `2026-02-14` | TOPOLOGY.md, THREAT-MODEL.md | ### Contact & Security @@ -71,7 +71,7 @@ sed -i "s/2026-03-16/$(date +%Y-%m-%d)/g" $(grep -rl '2026-03-16' .) | `[PGP fingerprint not set]` | 40-char PGP fingerprint | `ABCD 1234 ...` | SECURITY.md | | `{{PGP_KEY_URL}}` | URL to public PGP key | `https://keys.openpgp.org/...` | SECURITY.md | | `{{WEBSITE}}` | Project website | `https://example.org` | SECURITY.md | -| `{{CONDUCT_EMAIL}}` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | +| `j.d.a.jewell@open.ac.uk` | Conduct reports email | `conduct@example.org` | CODE_OF_CONDUCT.md | | `{{CONDUCT_TEAM}}` | Conduct committee name | `Code of Conduct Committee` | CODE_OF_CONDUCT.md | | `{{RESPONSE_TIME}}` | SLA for initial response | `48 hours` | CODE_OF_CONDUCT.md | diff --git a/QUICKSTART-MAINTAINER.adoc b/QUICKSTART-MAINTAINER.adoc index feca358..e9e8a24 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 intsoc-transactor, {{PACKAGE_NAME}}, {{DEPS}} with actuals +// Replace intsoc-transactor, intsoc-transactor, {{DEPS}} with actuals = intsoc-transactor — Quick Start for Platform Maintainers :toc: :toclevels: 2 @@ -65,10 +65,10 @@ Files installed: | `$PREFIX/bin/` | Executables -| `$PREFIX/share/{{PACKAGE_NAME}}/` +| `$PREFIX/share/intsoc-transactor/` | Data files, assets -| `$PREFIX/share/doc/{{PACKAGE_NAME}}/` +| `$PREFIX/share/doc/intsoc-transactor/` | 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/intsoc-transactor/config.toml` -Fallback: `$HOME/.config/{{PACKAGE_NAME}}/config.toml` +Fallback: `$HOME/.config/intsoc-transactor/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 intsoc-transactor` == 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/intsoc-transactor-instance1 --config=/etc/intsoc-transactor/instance1.toml +just install --prefix=/opt/intsoc-transactor-instance2 --config=/etc/intsoc-transactor/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..6f3569e --- /dev/null +++ b/REQUIRES_INITIALISATION.md @@ -0,0 +1,323 @@ + + +# REQUIRES INITIALISATION + +**This repository is not finished being set up.** 39 substitution token(s) across 8 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. + +## What is needed, and where it goes + +### `{{AUTHOR_EMAIL_ALT}}` + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{AUTHOR_ORG}}` + +Author's organisation. NOTE: no filled instance of this exists anywhere in the estate — consider deleting the field instead. + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{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` + +### `{{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: + +- `PLACEHOLDERS.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` + +### `{{DILITHIUM5_PUBLIC_KEY}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{DOMAIN}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{DRAFT_NAME}}` + +Appears in: + +- `nickel/contracts/boilerplate.ncl` + +### `{{ED448_PUBLIC_KEY}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{EXPIRES_AT}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{EXPIRY_DATE}}` + +Appears in: + +- `nickel/contracts/boilerplate.ncl` + +### `{{FALLBACK_SIGNATURE}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{GENERATED_AT}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{LANG_STACK}}` + +The language stack, in prose. + +Appears in: + +- `QUICKSTART-DEV.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` +- `PLACEHOLDERS.md` + +### `{{PLACEHOLDERS}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{PRIMARY_SIGNATURE}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{PROJECT_DESCRIPTION}}` + +One-line description, matching the forge description. + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{PROJECT_PURPOSE}}` + +One line: what this exists to do. + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{PROJECT_UNIQUE_STRENGTH}}` + +What this does that its alternatives do not. + +Appears in: + +- `.machine_readable/agent_instructions/methodology.a2ml` + +### `{{RESPONSE_TIME}}` + +Initial-response SLA for a security or conduct report. Promise only what a solo maintainer can actually meet. + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{SHA3_512}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{SHAKE256}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{SPHINCS_PLUS_PUBLIC_KEY}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{TEST_CMD}}` + +The exact command that runs its tests. + +Appears in: + +- `QUICKSTART-DEV.adoc` + +### `{{TRUSTFILE_PATH}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{TRUSTFILE_VERSION}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +### `{{WEBSITE}}` + +Project homepage URL, or delete the field if there is none. + +Appears in: + +- `PLACEHOLDERS.md` + +### `{{YEAR}}` + +Appears in: + +- `nickel/contracts/boilerplate.ncl` + +### `{{ZONEMD}}` + +Appears in: + +- `.machine_readable/contractiles/trust/Trustfile.a2ml` + +--- + +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`.