From dcae4ba36069f81090240c0480e676044dee1ea1 Mon Sep 17 00:00:00 2001 From: Sebastian Fastner Date: Tue, 16 Jun 2026 21:39:06 +0000 Subject: [PATCH] chore: standards v2 --- .oxfmtignore | 1 + .repometa.json | 2 +- .standards/pending.json | 22 ++++++++++++++++++++++ 3 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 .standards/pending.json diff --git a/.oxfmtignore b/.oxfmtignore index a4d523f..876d9b3 100644 --- a/.oxfmtignore +++ b/.oxfmtignore @@ -4,3 +4,4 @@ coverage node_modules pnpm-lock.yaml CHANGELOG.md +.standards/ diff --git a/.repometa.json b/.repometa.json index dd5af18..3299b17 100644 --- a/.repometa.json +++ b/.repometa.json @@ -1,5 +1,5 @@ { - "standards": 1, + "standards": 2, "visibility": "oss", "since": 2026 } diff --git a/.standards/pending.json b/.standards/pending.json new file mode 100644 index 0000000..a9bfb4a --- /dev/null +++ b/.standards/pending.json @@ -0,0 +1,22 @@ +{ + "schemaVersion": 1, + "fromVersion": 1, + "toVersion": 2, + "scopes": [ + "common", + "node" + ], + "visibility": "oss", + "exceptions": [], + "prompt": "You are migrating this repository to the Sebastian Software org standards.\n\nContext:\n- Previous standards version: 1, target: 2\n- Detected scopes: common, node\n- visibility: oss, since: 2026\n- Documented exceptions: []\n- The mechanical part (`standards apply`) has already been executed; managed\n files, seeded files, branding section and the version stamp are up to date.\n\nYour job is the judgement part: carry out the migration steps of the changelog\nentries below that apply to this repository, following the instructions.\n\n# Sebastian Software repository standards — agent instructions\n\nYou are updating a repository of the `sebastian-software` GitHub org to match\nthe org-wide standards defined in this package. Work changelog-driven, prefer\nthe CLI for mechanics, use judgement only where the changelogs require it.\n\n## The model\n\n- Every managed repository carries a `.repometa.json`:\n `{ \"standards\": , \"visibility\": \"oss\" | \"private\", \"since\": , \"exceptions\": [...] }`\n- `manifest.json` (in this package) defines the current standards version and,\n per scope, which files are **managed** (byte-exact sync), **seeded** (created\n once, repos may adapt them) and which README **sections** (marker-delimited\n blocks) are owned by the standards.\n- `changes/NNNN-*.md` are migration changelogs. Each declares the scopes it\n applies to and describes intent, mechanical steps and judgement calls.\n- Scopes are detected from the working tree: `common` always applies, `node`\n if `package.json` exists, `rust` if `Cargo.toml` exists (not yet defined).\n\n## Workflow\n\n1. Run `standards check` (CLI of this package; `pnpm dlx @sebastian-software/standards check`\n in repos that do not have it as a devDependency). If it reports nothing,\n you are done.\n2. Run `standards apply`. It writes managed files, seeds missing ones, updates\n branding sections and bumps the stamp. This covers the mechanical part only.\n3. Read every entry in `changes/` with a number greater than the repo's\n previous `standards` stamp, skipping entries whose scope does not apply.\n Carry out their migration steps — this is the part that needs judgement\n (merging configs the repo has customised, removing replaced tooling,\n adjusting package.json scripts).\n4. Verify with the repo's own gate: `pnpm agent:check` if present, otherwise\n lint + format check + typecheck + build + test individually.\n5. Open a PR titled `chore: standards v`. Never push to the default branch.\n\n## Rules\n\n- **Never reintroduce Prettier.** oxfmt is the org formatter. If a repo still\n uses Prettier, migrating away from it is part of the job (see change 0001).\n- **Seeded files are owned by the repo.** Do not overwrite local adaptations —\n merge the intent of the change into them instead.\n- **Branding sections are owned by the standards.** Never hand-edit content\n between `` markers; never\n remove the markers. `visibility: private` repos get the plain copyright\n footer, no marketing.\n- **Respect `exceptions`.** Entries in `.repometa.json#exceptions` document\n deliberate deviations (e.g. `\"keeps-prettier\"`). Skip the matching steps and\n leave the exceptions in place.\n- **Do not invent standards.** If something is unclear or a reference file is\n missing for the repo's stack, stop and report instead of improvising.\n\n\n## Changelog entries to execute\n\n### 0002-renovate-pending.md\n\n# 0002 — Renovate as the single driver for standards updates\n\n- **Scopes:** common\n- **Standards version:** 2\n\n## Intent\n\nFrom this version on, standards updates across all managed repos are\ninitiated uniformly by the self-hosted Renovate server. Renovate handles\nboth version detection (bump of `.repometa.json#standards`) and the\nmechanical sync (`standards apply`). The judgement part is performed by\nan externally triggered LLM agent (OpenClaw, local Claude Code, or\nCodex) in pull mode. The agent deliberately does not run inside the\nRenovate container.\n\n## Mechanical steps (covered by `standards apply`)\n\n- No file changes in target repos beyond what previous changelogs already\n required. The `.standards/pending.json` marker is written by Renovate's\n `postUpgradeTasks` step when `standards apply --emit-pending` is invoked\n with a non-zero set of pending judgement entries.\n\n## Judgement steps (agent work)\n\n- None at consumer level. This change is structural — it changes how\n future versions of `@sebastian-software/standards` are rolled out across\n the org, not what consumer repos contain.\n\n## Notes\n\n- **Per-repo bootstrap (manual, one-off):** the repo carries the existing\n `managed-deps` topic of the Renovate server. `.repometa.json` is\n created by running `pnpm dlx @sebastian-software/standards init`\n (interactive prompts for visibility and initial year; flags are\n available for CI). The onboarding PR (`Configure Renovate`) has to\n be merged once before standards drift becomes visible in the UI.\n- **Renovate server prerequisite:** a custom datasource reads\n `manifest.json#currentVersion` as an integer directly from the\n standards repo instead of using the published package's npm semver.\n This keeps the version model stack-agnostic (Rust, doc-only, or mixed\n repos never see a semver) and the PR title follows the\n `chore: standards v` convention from `SKILL.md`.\n- **Self-hosted Renovate is mandatory.** Mend Cloud (the GitHub App)\n does not support `postUpgradeTasks`. `allowedCommands` must permit\n the exact `apply` invocation; `executionMode: \"branch\"` avoids known\n problems with `executionMode: \"update\"`.\n- **Pull model:** Renovate opens the PR and writes\n `.standards/pending.json` when judgement steps exist. An external\n agent consumes the file, commits the judgement changes onto the same\n branch, and removes any `standards:needs-agent` label that was set.\n On Forgejo, label setting is less reliable than on GitHub — pull\n consumers should filter primarily on the presence of the file, not\n exclusively on the label.\n- **`apply` write contract:** `standards apply` writes only to\n (a) managed/seeded targets declared in `manifest.json`,\n (b) branding sections declared in `manifest.json`,\n (c) `.repometa.json#standards`, and (d) the path passed via\n `--emit-pending`. This makes broad `fileFilters: [\"**/*\"]` safe on the\n server side.\n- **Consumer tools outside the standards scopes** (Prettier leftovers\n during migration, Biome, gitleaks, dependabot configs,\n semantic-release pipelines, custom lint scripts) must ignore\n `.standards/` themselves when they would otherwise scan every repo\n path. The standards-scope ignore files (`oxfmtignore`, `cspell.json`)\n are maintained by the standards package; foreign tools are out of\n scope.\n", + "changes": [ + { + "file": "0002-renovate-pending.md", + "version": 2, + "scopes": [ + "common" + ], + "content": "# 0002 — Renovate as the single driver for standards updates\n\n- **Scopes:** common\n- **Standards version:** 2\n\n## Intent\n\nFrom this version on, standards updates across all managed repos are\ninitiated uniformly by the self-hosted Renovate server. Renovate handles\nboth version detection (bump of `.repometa.json#standards`) and the\nmechanical sync (`standards apply`). The judgement part is performed by\nan externally triggered LLM agent (OpenClaw, local Claude Code, or\nCodex) in pull mode. The agent deliberately does not run inside the\nRenovate container.\n\n## Mechanical steps (covered by `standards apply`)\n\n- No file changes in target repos beyond what previous changelogs already\n required. The `.standards/pending.json` marker is written by Renovate's\n `postUpgradeTasks` step when `standards apply --emit-pending` is invoked\n with a non-zero set of pending judgement entries.\n\n## Judgement steps (agent work)\n\n- None at consumer level. This change is structural — it changes how\n future versions of `@sebastian-software/standards` are rolled out across\n the org, not what consumer repos contain.\n\n## Notes\n\n- **Per-repo bootstrap (manual, one-off):** the repo carries the existing\n `managed-deps` topic of the Renovate server. `.repometa.json` is\n created by running `pnpm dlx @sebastian-software/standards init`\n (interactive prompts for visibility and initial year; flags are\n available for CI). The onboarding PR (`Configure Renovate`) has to\n be merged once before standards drift becomes visible in the UI.\n- **Renovate server prerequisite:** a custom datasource reads\n `manifest.json#currentVersion` as an integer directly from the\n standards repo instead of using the published package's npm semver.\n This keeps the version model stack-agnostic (Rust, doc-only, or mixed\n repos never see a semver) and the PR title follows the\n `chore: standards v` convention from `SKILL.md`.\n- **Self-hosted Renovate is mandatory.** Mend Cloud (the GitHub App)\n does not support `postUpgradeTasks`. `allowedCommands` must permit\n the exact `apply` invocation; `executionMode: \"branch\"` avoids known\n problems with `executionMode: \"update\"`.\n- **Pull model:** Renovate opens the PR and writes\n `.standards/pending.json` when judgement steps exist. An external\n agent consumes the file, commits the judgement changes onto the same\n branch, and removes any `standards:needs-agent` label that was set.\n On Forgejo, label setting is less reliable than on GitHub — pull\n consumers should filter primarily on the presence of the file, not\n exclusively on the label.\n- **`apply` write contract:** `standards apply` writes only to\n (a) managed/seeded targets declared in `manifest.json`,\n (b) branding sections declared in `manifest.json`,\n (c) `.repometa.json#standards`, and (d) the path passed via\n `--emit-pending`. This makes broad `fileFilters: [\"**/*\"]` safe on the\n server side.\n- **Consumer tools outside the standards scopes** (Prettier leftovers\n during migration, Biome, gitleaks, dependabot configs,\n semantic-release pipelines, custom lint scripts) must ignore\n `.standards/` themselves when they would otherwise scan every repo\n path. The standards-scope ignore files (`oxfmtignore`, `cspell.json`)\n are maintained by the standards package; foreign tools are out of\n scope.\n" + } + ] +}