From ccd46a11453fe875512b538fe47b27177cae2b3d Mon Sep 17 00:00:00 2001 From: Kyle Tse Date: Sun, 21 Jun 2026 19:22:17 +0100 Subject: [PATCH 1/4] docs: add project manifest --- .doctrine/project.json | 141 +++++++++++++++++++++++++++++++++++++++++ AGENTS.md | 11 ++++ PROJECT.md | 41 ++++++++++++ 3 files changed, 193 insertions(+) create mode 100644 .doctrine/project.json create mode 100644 AGENTS.md create mode 100644 PROJECT.md diff --git a/.doctrine/project.json b/.doctrine/project.json new file mode 100644 index 0000000..10bdccc --- /dev/null +++ b/.doctrine/project.json @@ -0,0 +1,141 @@ +{ + "schemaVersion": 1, + "project": { + "repo": "SylphxAI/bump", + "name": "SylphxAI Bump", + "lifecycle": "production", + "layer": "tooling", + "summary": "Bun-based semantic release, changelog, and package publishing tool with a CLI and composite GitHub Action.", + "goals": [ + "Provide the @sylphx/bump CLI for semantic versioning, changelog generation, release PRs, and package publishing.", + "Provide the composite GitHub Action surface used by repositories that want bump-driven release automation.", + "Support monorepo package detection, workspace dependency resolution, bump files, prereleases, GitHub releases, and npm publication." + ], + "nonGoals": [ + "Own the products or packages that consume bump.", + "Own organization-wide branch protection, release approval policy, npm token rotation, or package registry operations.", + "Own enterprise engineering doctrine, standards, or project manifest schema." + ] + }, + "boundaries": { + "owns": [ + { + "name": "bump-cli", + "description": "The CLI entry point, commands, release engine, changelog generation, package detection, and npm/GitHub integration code under src." + }, + { + "name": "bump-github-action", + "description": "The composite action.yml and detect/action.yml surfaces used by consuming repositories." + }, + { + "name": "bump-validation", + "description": "Bun-based tests, lint/typecheck/build scripts, workflow examples, and release workflow for this package." + } + ], + "doesNotOwn": [ + "Release eligibility, branch protection, secrets, package contents, or deployment outcomes in consuming repositories.", + "Organization-wide package registry administration, npm token rotation, or release approval policy.", + "Enterprise doctrine and manifest schema owned by SylphxAI/doctrine." + ], + "publicSurfaces": [ + { + "type": "documentation", + "name": "CLI and package README", + "location": "README.md" + }, + { + "type": "manifest", + "name": "Package manifest and scripts", + "location": "package.json" + }, + { + "type": "cli", + "name": "Bump CLI entry point", + "location": "src/cli.ts" + }, + { + "type": "api", + "name": "Release core", + "location": "src/core/" + }, + { + "type": "api", + "name": "GitHub adapter", + "location": "src/adapters/github.ts" + }, + { + "type": "workflow", + "name": "Composite GitHub Action", + "location": "action.yml" + }, + { + "type": "workflow", + "name": "CI and release workflows", + "location": ".github/workflows/" + }, + { + "type": "test", + "name": "Bun test suite", + "location": "tests/" + } + ], + "allowedDependencies": [ + { + "repo": "SylphxAI/doctrine", + "surface": "project manifest schema and engineering doctrine", + "direction": "peer-public" + } + ], + "forbiddenCouplings": [ + "Do not encode a consuming repository's product release policy as bump core behavior.", + "Do not store registry credentials or organization release approvals in this package.", + "Do not fork doctrine standards into this repository." + ] + }, + "documentation": { + "adr": { + "path": "docs/adr/", + "status": "planned" + }, + "specs": { + "path": "README.md", + "status": "present" + }, + "catalog": { + "path": ".doctrine/project.json", + "status": "present" + }, + "runbooks": { + "path": "docs/runbooks/", + "status": "planned" + }, + "generatedReferences": { + "path": "CHANGELOG.md", + "status": "present" + } + }, + "delivery": { + "ciModel": "legacy-ci", + "requiredContexts": [], + "deployPath": "Main-branch Release workflow builds the package and dogfoods the local composite action to create release PRs or publish with NPM_TOKEN.", + "productionProof": "Passing bun run lint, bun run typecheck, bun test, bun run build, and successful release workflow or registry readback for published versions.", + "recoveryClass": "forward-fix-only" + }, + "adoption": { + "status": "baseline", + "gaps": [ + { + "id": "required-contexts-not-recorded", + "description": "CI exists for pull requests and merge queue, but required branch protection contexts are not recorded in this manifest baseline.", + "owner": "SylphxAI/bump", + "target": "central ADR-29 required-context rollout or repo-local branch protection audit" + }, + { + "id": "release-runbook-missing", + "description": "Package publication uses GitHub and npm tokens; add a runbook for failed release PRs, failed publishes, and registry forward fixes.", + "owner": "SylphxAI/bump", + "target": "before next release workflow change" + } + ] + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..49297f2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,11 @@ +# Agent Instructions + +This repository consumes the Sylphx engineering doctrine from [SylphxAI/doctrine](https://github.com/SylphxAI/doctrine). + +Before changing files here: + +- Read [PROJECT.md](./PROJECT.md) and [`.doctrine/project.json`](./.doctrine/project.json) for this repository's goal, lifecycle, boundary, public surfaces, and adoption gaps. +- Read `SylphxAI/doctrine` `AGENTS.md`, `PRINCIPLES.md`, and `ADR.md`, then load any triggered standards. +- Keep bump behavior generic to release automation; consuming repository release policy belongs in the consuming repository. + +Do not encode product-specific release rules here. This repository owns bump release tooling only. diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..6bd0cf1 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,41 @@ +# SylphxAI Bump + +SylphxAI/bump is a Bun-based semantic release, changelog, and package publishing tool with a CLI and composite GitHub Action. + +## Lifecycle + +- State: `production` +- Layer: `tooling` +- Machine manifest: [`.doctrine/project.json`](./.doctrine/project.json) + +## Goals + +- Provide the `@sylphx/bump` CLI for semantic versioning, changelog generation, release PRs, and package publishing. +- Provide the composite GitHub Action surface used by repositories that want bump-driven release automation. +- Support monorepo package detection, workspace dependency resolution, bump files, prereleases, GitHub releases, and npm publication. + +## Non-Goals + +- This repository does not own the products or packages that consume bump. +- This repository does not own organization-wide branch protection, release approval policy, npm token rotation, or package registry operations. +- This repository does not own enterprise engineering doctrine. + +## Boundary + +This repository owns bump's CLI, release engine, GitHub Action wrapper, tests, examples, package metadata, and release workflow. Consuming repositories own their release eligibility, secrets, package contents, and deployment outcomes. + +## Public Surfaces + +- CLI and package README: [`README.md`](./README.md) +- Package manifest and scripts: [`package.json`](./package.json) +- CLI entry point: [`src/cli.ts`](./src/cli.ts) +- Release core: [`src/core/`](./src/core/) +- GitHub adapter: [`src/adapters/github.ts`](./src/adapters/github.ts) +- Composite action: [`action.yml`](./action.yml) +- Detect action: [`detect/action.yml`](./detect/action.yml) +- Workflow examples: [`examples/`](./examples/) +- CI and release workflows: [`.github/workflows/`](./.github/workflows/) + +## Delivery + +The repository has Bun-based CI for pull requests and merge queue, plus a main-branch release workflow that dogfoods the local composite action. Production proof is passing lint/typecheck/tests/build plus release workflow evidence for package publication. This manifest slice is documentation-only and does not change release behavior, package code, CI, or publishing configuration. From 74ccc5fffd287393183e89213cfc935d21061338 Mon Sep 17 00:00:00 2001 From: Kyle Tse Date: Sun, 21 Jun 2026 19:24:48 +0100 Subject: [PATCH 2/4] docs: record lint adoption gap --- .doctrine/project.json | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.doctrine/project.json b/.doctrine/project.json index 10bdccc..6b04b9d 100644 --- a/.doctrine/project.json +++ b/.doctrine/project.json @@ -130,6 +130,12 @@ "owner": "SylphxAI/bump", "target": "central ADR-29 required-context rollout or repo-local branch protection audit" }, + { + "id": "biome-lint-existing-debt", + "description": "Current CI fails on existing Biome lint/format diagnostics in source and test files before this documentation-only manifest PR can merge.", + "owner": "SylphxAI/bump", + "target": "before this repository can accept documentation-only PRs through current CI" + }, { "id": "release-runbook-missing", "description": "Package publication uses GitHub and npm tokens; add a runbook for failed release PRs, failed publishes, and registry forward fixes.", From 8afa8aee902822f67980a215c9b0126fa6e42929 Mon Sep 17 00:00:00 2001 From: Kyle Tse Date: Tue, 23 Jun 2026 00:01:48 +0100 Subject: [PATCH 3/4] docs: add ADR-81 selector facts --- .doctrine/project.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.doctrine/project.json b/.doctrine/project.json index 6b04b9d..699eb0f 100644 --- a/.doctrine/project.json +++ b/.doctrine/project.json @@ -5,6 +5,7 @@ "name": "SylphxAI Bump", "lifecycle": "production", "layer": "tooling", + "policyPool": "agent-tool", "summary": "Bun-based semantic release, changelog, and package publishing tool with a CLI and composite GitHub Action.", "goals": [ "Provide the @sylphx/bump CLI for semantic versioning, changelog generation, release PRs, and package publishing.", @@ -116,6 +117,7 @@ }, "delivery": { "ciModel": "legacy-ci", + "deployable": false, "requiredContexts": [], "deployPath": "Main-branch Release workflow builds the package and dogfoods the local composite action to create release PRs or publish with NPM_TOKEN.", "productionProof": "Passing bun run lint, bun run typecheck, bun test, bun run build, and successful release workflow or registry readback for published versions.", From 2ece99b38915ea4484fe5e35f6fbb9b43f29a146 Mon Sep 17 00:00:00 2001 From: Kyle Tse Date: Tue, 23 Jun 2026 00:03:57 +0100 Subject: [PATCH 4/4] docs: declare package release facts --- .doctrine/project.json | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/.doctrine/project.json b/.doctrine/project.json index 699eb0f..be22391 100644 --- a/.doctrine/project.json +++ b/.doctrine/project.json @@ -121,7 +121,23 @@ "requiredContexts": [], "deployPath": "Main-branch Release workflow builds the package and dogfoods the local composite action to create release PRs or publish with NPM_TOKEN.", "productionProof": "Passing bun run lint, bun run typecheck, bun test, bun run build, and successful release workflow or registry readback for published versions.", - "recoveryClass": "forward-fix-only" + "recoveryClass": "forward-fix-only", + "packageRelease": { + "publishesPackages": true, + "ecosystems": [ + "npm", + "github-release", + "github-action" + ], + "releaseIntent": "Bump files and conventional commits are this repository's Changesets-equivalent release intent, as documented in README.md.", + "versionPr": "Current release workflow dogfoods the local composite action to create release PRs; ADR-59 target is bot/GitHub App-owned version PRs through sylphx-release-bot before ratchet.", + "publisher": "Protected GitHub Actions release workflow publishes with NPM_TOKEN as a bounded token fallback until npm OIDC/trusted publishing and provenance are adopted.", + "requiredContexts": [ + "CI / test", + "release evidence / registry readback" + ], + "publishProof": "npm registry readback for @sylphx/bump, GitHub release or tag readback, and provenance or attestation evidence when trusted publishing is adopted." + } }, "adoption": { "status": "baseline",