Merge pull request #5 from shobman/feature/aidos-versioning

feat(versioning): introduce AIDOS framework versioning and migrations

Author: shobman

.gitattributes

@@ -0,0 +1 @@
+VERSION text eol=lf

.gitignore

@@ -9,3 +9,7 @@ Thumbs.db
 *.swo
 *~
 skills/dist/
+
+# Internal planning artifacts — not shipped in the public repo
+.claude/
+docs/superpowers/

CLAUDE.md

@@ -35,3 +35,17 @@ separate session.
 ```
 
 The `.aidos/manifest.json` in your project configures both the GitHub MCP Connector's `write` strategy and the Confluence publish target (if used). See each connector's README for the manifest fields.
+
+## Migrations
+
+When modifying templates, rubrics, naming conventions, or artifact structure in `src/prompts/`, `src/templates/`, `src/rubrics/`, `src/framework.md`, or `skills/`:
+
+1. Determine if the change affects the structure or naming of generated artifacts, or the metadata block. If yes, this is a **minor** version bump.
+2. Increment the middle segment in the repo-root `VERSION` file (e.g. `1.0.0` → `1.1.0`).
+3. Create a migration file at `src/migrations/vX.Y.Z-to-vX.Y+1.0.md` (e.g. `v1.0.0-to-v1.1.0.md`) following the format in `src/migrations/README.md`. Write the instructions so an AI agent can apply them to a single artifact file at a time.
+4. Update the `**AIDOS Version:** X.Y.Z` placeholder in any affected template to keep it in sync with `VERSION`.
+5. If the change is wording-only with no structural impact (rubric clarifications, prompt tweaks), it's a **patch** bump — increment the last segment of `VERSION`. No migration file needed.
+
+Major version bumps (e.g. `1.x.x` → `2.0.0`) are reserved for fundamental redesigns where automated migration may not be feasible. If you think you're looking at a major bump, stop and discuss it before proceeding — major bumps are not in scope for the current framework generation.
+
+After a version bump, tag the repo: `git tag vX.Y.Z`.

VERSION

@@ -0,0 +1 @@
+1.0.0

skills/auditor/SKILL.md

@@ -31,6 +31,7 @@ When the user presents an artifact for review, you:
 | `rubrics/definition.md` | Definition rubric (F1–F8). Maintenance lens criteria for post-delivery Definitions. |
 | `templates/retrospective.md` | Retrospective template for rubric evolution. |
 | `CONTRIBUTING.md` | How to propose rubric changes — the contribution model for evolving the framework. |
+| `VERSION` | **Framework version.** Plain-text file containing the current AIDOS framework semver (e.g. `1.0.0`). Read on session start — used to compare against the audited file's `AIDOS Version` metadata. |
 
 ## Environment
 

skills/build.ps1

@@ -21,6 +21,7 @@ function Fix-PromptPaths {
     $content = Get-Content $File -Raw
     $content = $content -replace '`src/rubrics/', '`rubrics/'
     $content = $content -replace '`src/templates/', '`templates/'
+    $content = $content -replace '`src/migrations/', '`migrations/'
     $content = $content -replace '`src/framework\.md`', '`framework.md`'
     Set-Content $File $content -NoNewline
 }
@@ -67,6 +68,15 @@ try {
     Copy-To (Join-Path $root "src\templates\retrospective.md")      (Join-Path $b "templates\retrospective.md")
     Copy-To (Join-Path $root "CONTRIBUTING.md")                    (Join-Path $b "CONTRIBUTING.md")
 
+    Copy-To (Join-Path $root "VERSION")                            (Join-Path $b "VERSION")
+
+    $migSrc = Join-Path $root "src\migrations"
+    if (Test-Path $migSrc) {
+        Get-ChildItem $migSrc -File | ForEach-Object {
+            Copy-To $_.FullName (Join-Path $b "migrations\$($_.Name)")
+        }
+    }
+
     Fix-PromptPaths (Join-Path $b "builder-prompt.md")
 
     New-SkillZip -Name "aidos-builder" -StagingDir $b -OutPath (Join-Path $dist "aidos-builder.zip")
@@ -86,6 +96,8 @@ try {
     Copy-To (Join-Path $root "src\templates\retrospective.md")     (Join-Path $a "templates\retrospective.md")
     Copy-To (Join-Path $root "CONTRIBUTING.md")                   (Join-Path $a "CONTRIBUTING.md")
 
+    Copy-To (Join-Path $root "VERSION")                           (Join-Path $a "VERSION")
+
     Fix-PromptPaths (Join-Path $a "auditor-prompt.md")
 
     New-SkillZip -Name "aidos-auditor" -StagingDir $a -OutPath (Join-Path $dist "aidos-auditor.zip")

skills/builder/SKILL.md

@@ -34,6 +34,8 @@ When the user describes work they want to deliver, you:
 | `templates/definition.md` | Definition artifact template with section-to-rubric mapping. |
 | `templates/retrospective.md` | Retrospective template for rubric evolution. |
 | `CONTRIBUTING.md` | How to propose rubric changes — the contribution model for evolving the framework. |
+| `VERSION` | **Framework version.** Plain-text file containing the current AIDOS framework semver (e.g. `1.0.0`). Read on session start and before opening each existing artifact — used to stamp new artifacts and compare against existing files' `AIDOS Version` metadata. |
+| `migrations/` | Directory of `vX.Y.Z-to-vX.Y+1.0.md` files (e.g. `v1.0.0-to-v1.1.0.md`) describing how to upgrade artifacts across minor framework bumps. Read only when a file is behind and the user accepts an upgrade. |
 
 ## Environment
 

src/connectors/confluence/README.md

@@ -32,7 +32,7 @@ on:
 
 jobs:
   publish:
-    uses: shobman/aidos/.github/workflows/confluence-publish.yml@main
+    uses: shobman/aidos/.github/workflows/confluence-publish.yml@v1.0.0
     with:
       manifest-path: .aidos/manifest.json
       dry-run: ${{ github.event_name == 'pull_request' }}
@@ -41,6 +41,8 @@ jobs:
       confluence_token: ${{ secrets.CONFLUENCE_TOKEN }}
 ```
 
+> **Pin a tag, not `@main` or `@sha`.** AIDOS releases are tagged using semver (`vX.Y.Z`). Pinning to a tag means your workflow stays on a known-good version and only moves when you bump the pin. The tag to use is the current AIDOS framework version — see the `VERSION` file at the root of the AIDOS repo.
+
 PRs dry-run (preview in the Actions log), merges to main publish for real.
 
 If your repo has multiple `.aidos/` folders (e.g. a monorepo), omit `manifest-path` and the workflow will auto-discover all `manifest.json` files.
@@ -186,6 +188,30 @@ Each connector reads only its own key and ignores the rest.
 
 Validate your manifest against `manifest.schema.json` in this directory.
 
+## Org-Restricted Environments
+
+Some organisations block all public GitHub Actions by policy. If your org's workflow policy rejects `uses: shobman/aidos/...@v1.0.0`, you have two options:
+
+### Option 1 — Vendor the workflow
+
+Fork the AIDOS repo into your org, or copy `.github/workflows/confluence-publish.yml` and `src/connectors/confluence/` into an internal repo. Reference it by internal path instead:
+
+```yaml
+    uses: your-org/internal-aidos/.github/workflows/confluence-publish.yml@v1.0.0
+```
+
+Tag your internal fork with the same version as the upstream AIDOS release it's based on. When upstream cuts a new release, pull the changes in and re-tag.
+
+### Option 2 — Inline the workflow
+
+If forking isn't practical, write a workflow in your consuming repo that runs the publish script directly. You'll need to vendor `src/connectors/confluence/publish.js` (and its dependencies) into your repo as well. Track which upstream version you're based on in the workflow file's comments — the AIDOS version in your artifact files tells you which release's publish script to align with.
+
+### Tracking alignment
+
+In either option, the `**AIDOS Version:**` field in your artifact files is the source of truth for "what AIDOS version should this workflow be running". If artifacts are on v1.1.0, the workflow should be on the v1.1.0 release. Minor-version mismatches between artifacts and the workflow are not guaranteed compatible — migrate artifacts first, then bump the workflow pin. Patch-version drift is safe.
+
+---
+
 ## Develop
 
 ### Get the code
@@ -241,4 +267,4 @@ The script is ~700 lines, self-contained, ESM, uses Node 20+ built-in fetch. Fol
 
 ### Versioning
 
-No semver. The connector is versioned alongside the aidos repo. The GitHub Actions workflow pulls from `shobman/aidos@main` (or a pinned tag if you want stability). Bump the `CONNECTOR_VERSION` constant in `publish.js` to force republish of all pages — useful after output format changes.
+The connector is versioned alongside the aidos repo using semver (`vX.Y.Z`). Consumers pin the GitHub Actions workflow to a tag — see the Install section above for the tag-pinning requirement. Bump the `CONNECTOR_VERSION` constant in `publish.js` to force republish of all pages — useful after output format changes.

src/migrations/.gitkeep

@@ -0,0 +1,46 @@
+# AIDOS Migrations
+
+Migration files describe how to upgrade an AIDOS artifact from one framework version to the next. One file per minor version bump.
+
+## File naming
+
+`vX.Y.Z-to-vX.Y+1.0.md` — e.g. `v1.0.0-to-v1.1.0.md`, `v1.1.0-to-v1.2.0.md`.
+
+Patch bumps (v1.0.0 → v1.0.1) never have migrations. Patches are wording-only.
+
+## File format
+
+Each migration is a markdown file with a title and up to four sections. Sections are present only when they apply. Example:
+
+```
+# Migration v1.0.0 → v1.1.0
+
+## Summary
+Brief human-readable description of what changed and why.
+
+## File renames
+- `Problem.md` → `1. Problem.md`
+- `Solution.md` → `2. Solution.md`
+- `Tech Design.md` → `3. Tech Design.md`
+- `Test Strategy.md` → `4. Test Strategy.md`
+
+## Content changes
+- In `1. Problem.md`, rename the heading "## Business Context" to "## Context"
+
+## Metadata changes
+None.
+```
+
+## Who reads these files
+
+The AIDOS builder skill, when it opens an artifact file whose `AIDOS Version` is behind the current framework version. It reads the relevant migration files, applies them to the file in question (only the parts that affect that file), presents a diff for user signoff, then updates the file's `AIDOS Version` metadata.
+
+The AIDOS auditor skill does not read these files. It reads only the `AIDOS Version` metadata field from artifact files and compares it against `VERSION` to warn users about version gaps.
+
+## Who writes these files
+
+Any developer (human or AI) who changes the structure, naming, or shape of AIDOS artifacts. The developer guardrail in the repo's `CLAUDE.md` reminds contributors to create a migration file for any minor-version change.
+
+## Scope rule
+
+Instructions should be written so an AI agent can apply them to a single file at a time. A workspace can have files at mixed versions — each file migrates independently as the user opens it.