diff --git a/adr/refined/ADR1_application-size.md b/adr/approved/ADR1_application-size.md similarity index 99% rename from adr/refined/ADR1_application-size.md rename to adr/approved/ADR1_application-size.md index 54a9805..d102d5d 100644 --- a/adr/refined/ADR1_application-size.md +++ b/adr/approved/ADR1_application-size.md @@ -1,7 +1,7 @@ **ID:** ADR1 \ **Title:** Application size \ **Supersedes:** - \ -**Status:** REFINED \ +**Status:** APPROVED \ **Expiration Date:** Six months after approval; record the calendar date upon manual approval. ## Context diff --git a/adr/refined/ADR2_http-api-contracts-and-tooling.md b/adr/approved/ADR2_http-api-contracts-and-tooling.md similarity index 99% rename from adr/refined/ADR2_http-api-contracts-and-tooling.md rename to adr/approved/ADR2_http-api-contracts-and-tooling.md index 32f8728..6c509b3 100644 --- a/adr/refined/ADR2_http-api-contracts-and-tooling.md +++ b/adr/approved/ADR2_http-api-contracts-and-tooling.md @@ -1,7 +1,7 @@ **ID:** ADR2 \ **Title:** HTTP API contracts and tooling \ **Supersedes:** - \ -**Status:** REFINED \ +**Status:** APPROVED \ **Expiration Date:** Six months after approval; record the calendar date upon manual approval. ## Context diff --git a/specs/refined/S19_multi-project b/specs/refined/S19_multi-project new file mode 100644 index 0000000..f3c1619 --- /dev/null +++ b/specs/refined/S19_multi-project @@ -0,0 +1,167 @@ +As developer +I want to separate landscape documentation and reusable engineering resources from Agile Dancers +so that I adhere to ADR1 and can start and maintain multiple projects with a complete, versioned engineering setup. + +Status: REFINED + +Architecture: ADR1, Application size (`adr/approved/ADR1_application-size.md` before migration). + +Affected repositories: + +- `agiledancers` (existing application repository) +- `landscape` (new repository) +- `engineering` (new repository) + +## Intent + +Create `landscape` and `engineering` on the existing Gitea server, under the same +owner as `agiledancers`. Check them out to `~/Projecten/git/landscape` and +`~/Projecten/git/engineering`. + +Keep Agile Dancers working throughout the migration. Fully generalize the +engineering setup so another project can start with a ready-to-use pipeline +recipe. Moving application-specific helpers unchanged into another repository +does not satisfy this specification. + +## Repository ownership + +### Landscape + +Move ADRs and specifications, including this specification, to `landscape`. +Maintain the capability and system map there, recording current boundaries and +leaving future business-system extraction to follow-up specifications. Each +specification identifies the repositories it affects. + +Landscape also contains instructions for starting projects that use this setup, +including repository creation, use of the engineering project generator, +configuration, secrets setup, and engineering upgrades. Link to engineering's +technical usage instructions rather than maintaining duplicate instructions. + +### Engineering + +Move reusable skills, general engineering documentation, coding standards, +tooling, and generalized pipeline and deployment mechanisms to `engineering`. +Include templates and a project generator for new consumers. + +Generalize the existing CI, deployment, formatting, standards, and coverage +helpers as needed. This includes helpers such as `ci/Pipeline.java`; substantial +generalization is part of S19 rather than deferred merely because it requires +more than a small configuration change. + +Keep upstream skill files unchanged. Preserve their revision records, licenses, +and attribution, including the files currently recorded in `skills/upstream.json`. + +### Application repositories + +Keep implementation code, executable tests, fixtures, historical application +validation reports, and implementation and operational instructions with their +application. Keep project-specific configuration and adapters here, including +Compose configuration, deployment targets, secret references, and existing +maintainer-approved standards waivers. Do not copy application waivers into +defaults for other projects. Do not commit secret values. + +Classify every existing resource in the ADR, specification, CI, deployment, +documentation, skills, and tooling folders. Record its destination and the reason +it moves or stays. For mixed resources, separate the general mechanism from +application configuration rather than assigning the whole folder one destination. + +## Versioned consumption and generation + +Release engineering as one package using semantic version tags such as `v1.0.0`. +Published tags are immutable; breaking changes require a new major version. +Consumers adopt upgrades explicitly and record both the selected tag and its +resolved commit. Reject a fetch when the tag no longer resolves to that commit. + +Copy the selected engineering resources into a committed `generated/` folder in +each consuming project. Record their source and version. Treat these files as +generated output: make general changes in engineering and regenerate the local +copy. Regeneration replaces generated content, including removal of obsolete +generated files, without overwriting project-owned files outside that folder. + +Provide a small project-local bootstrap script and version configuration outside +`generated/`. Add a Maven profile that invokes the script to regenerate from the +selected engineering version. The profile must work when `generated/` is absent; +it must not require generated tooling to bootstrap itself. + +Ordinary local builds use the committed resources without downloading or +regenerating them each time. Access to engineering can be assumed for explicit +regeneration and CI. No Nexus or other artifact repository is required. + +CI regenerates from the recorded tag and commit and fails if the resulting +generated files differ from the committed files, including added or removed +files. CI does not select a newer engineering release automatically. + +Keep Maven verification, standalone Docker builds, CI, and agent instructions +working with these paths. A fresh application clone must not depend on sibling +repository checkouts or globally installed project skills. + +## General pipeline recipe and project generator + +Support Gitea Actions, Maven/Java, npm, and Docker Compose. Projects can select a +backend, a frontend, or both. Other build systems and deployment platforms are +outside this specification. + +Make project names, module paths, image names, deployment servers and paths, +and healthchecks configurable. Provide shared build, test, image-build, +deployment, and rollback mechanisms. Application secrets remain configured by +the consuming project; engineering supplies the mechanism and instructions. + +Provide a command that creates a local project skeleton from templates using a +project name and the selected components. Include pipeline workflows, project +configuration, bootstrap script, engineering version configuration, and agent +instructions. Repository creation and secrets configuration are documented +setup steps rather than actions performed by this generator. + +The generator creates project-owned files such as `pom.xml`, workflows, and +Compose configuration once. Subsequent engineering upgrades automatically +replace only `generated/`. Supply upgrade instructions when project-owned files +also require changes. Keep these project-owned files thin by delegating shared +behavior to generated engineering resources. + +Include a small example project in engineering that consumes the same recipe +and proves it works without hidden Agile Dancers assumptions. Validate its +deployment and rollback in an isolated test environment. + +## Documentation and traceability + +Start the new repositories with attributed snapshots. Record the source +repository and source commit; retain the existing history in Agile Dancers. +Extracting Git history into the new repositories is not required. + +Update README, AGENTS, and affected links after moving files. Explain how agents +and maintainers locate landscape guidance, use the pinned engineering resources, +regenerate them, and adopt upgrades. Landscape guidance may be referenced at its +current revision; executable engineering resources remain pinned. Use fixed +commits where historical evidence needs a stable reference. + +Repair links between moved specifications and application validation evidence. +Each application's README continues to describe its implementation and operation. + +## Migration and acceptance criteria + +Migrate incrementally, keeping the application working after each extraction. +Complete the following before considering S19 implemented: + +1. Both new repositories exist in Gitea and at the agreed local checkout paths. +2. The resource classification is complete, destinations follow ADR1, and moved + files retain source attribution and applicable licenses. +3. Engineering has a tagged release, a documented generator and upgrade process, + and fully generalized mechanisms for the supported stack. +4. Agile Dancers consumes the recorded engineering tag and commit through + committed generated resources. Regeneration works from a clean checkout and + with `generated/` absent. CI detects generated-file drift and rejects a moved + tag without silently upgrading. +5. A clean Agile Dancers checkout passes the required build and test checks and + builds its Docker image without sibling checkouts. Its Gitea build workflow + succeeds with the new resource layout. +6. Agile Dancers deployment and rollback configuration is validated. Record any + behavior that cannot be verified without a production deployment as an + explicit validation limit. +7. The example project is generated from the recipe, builds and tests from a + clean checkout, and demonstrates deployment and rollback in an isolated + environment. +8. README, AGENTS, landscape onboarding instructions, and affected links explain + and correctly reference the resulting setup. + +Production deployment is a separate action. Business capability extraction, +runtime system boundaries, and migration of application data are outside S19.