chore: enforce semantic migration sequence

.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+
+      - name: Check migration sequence
+        run: npm run migrations:check
+
+      - name: Validate graph
+        run: npm run memory:graph:validate
+
+      - name: Run tests
+        run: npm test

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.3.1 - 2026-05-27
+
+PAM 0.3.1 adds automated semantic migration enforcement. The graph schema
+remains `pam-graph-v1`; this release adds a policy/tooling migration so future
+operational, runtime, agent, graph, and tool changes must declare a versioned
+migration path.
+
+### Added
+
+- Migration enforcement command: `npm run migrations:check`.
+- CI-friendly checks for:
+  - matching `package.json` and `memory/pam.version.json` versions;
+  - valid semver migration filenames;
+  - one-step patch/minor/major migration transitions;
+  - contiguous migration chains from the base version to the target version;
+  - migration-sensitive changes without a PAM version bump.
+- Migration-sensitive path policy for PAM runtime/tooling, graph files, agent
+  instructions, OpenClaw operational docs, and package metadata.
+- Test coverage for semantic migration path validation.
+
+### Compatibility
+
+- `memoryFormat` remains `graph-v1`.
+- `graphSchemaVersion` remains `pam-graph-v1`.
+- Existing 0.3.0 graph JSONL files remain valid.
+
 ## 0.3.0 - 2026-05-08
 
 PAM 0.3.0 adds an OpenClaw specialization profile and makes installation

memory/pam.version.json

@@ -1,13 +1,14 @@
 {
-  "pamVersion": "0.3.0",
+  "pamVersion": "0.3.1",
   "memoryFormat": "graph-v1",
   "graphSchemaVersion": "pam-graph-v1",
   "features": {
     "graphJsonl": true,
     "markdownLogs": true,
     "versionAwareMigration": true,
     "openClawSpecialization": true,
-    "installationAcceptanceCriteria": true
+    "installationAcceptanceCriteria": true,
+    "migrationEnforcement": true
   },
-  "updated": "2026-05-08"
+  "updated": "2026-05-27"
 }

migrations/0.3.0-to-0.3.1-migration-enforcement.md

@@ -0,0 +1,47 @@
+# PAM 0.3.0 -> 0.3.1 Migration: Semantic Migration Enforcement
+
+PAM 0.3.1 adds automated enforcement for semantic migration sequencing. This is
+an operational/tooling migration; it does not change `pam-graph-v1`.
+
+## Who Should Apply This
+
+Apply this migration when a workspace is on PAM 0.3.0 and wants future PAM
+updates to be applied as ordered semantic migrations instead of ad hoc release
+notes.
+
+## Changes
+
+- Update `package.json` and `memory/pam.version.json` to `0.3.1`.
+- Enable the `migrationEnforcement` feature flag.
+- Add `npm run migrations:check`.
+- Treat runtime/tooling, graph, agent-instruction, OpenClaw operational docs,
+  and package metadata changes as migration-sensitive.
+
+## Procedure
+
+1. Update the workspace to PAM 0.3.1.
+2. Run `npm run migrations:check`.
+3. If the check fails because a local branch changes migration-sensitive files,
+   either add the missing semver migration or explicitly split non-migration
+   docs-only changes into a separate branch.
+4. Run the normal graph validation:
+
+   ```bash
+   npm run memory:graph:validate
+   ```
+
+## Validation
+
+The migration is complete when:
+
+- `package.json` version is `0.3.1`.
+- `memory/pam.version.json` has `pamVersion: "0.3.1"`.
+- `memory/pam.version.json` has `features.migrationEnforcement: true`.
+- `npm run migrations:check` passes.
+- `npm run memory:graph:validate` passes.
+
+## Compatibility
+
+- `memoryFormat` remains `graph-v1`.
+- `graphSchemaVersion` remains `pam-graph-v1`.
+- Existing 0.3.0 graph JSONL files remain valid.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-memory",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "description": "Markdown-first portable memory, wiki, and maintenance toolkit for AI agents.",
   "type": "module",
@@ -18,6 +18,7 @@
     "memory:index": "node tools/memory-maintenance.mjs index",
     "memory:synthesis": "node tools/memory-maintenance.mjs synthesis",
     "memory:schedule:install": "node tools/install-memory-maintenance-schedule.mjs",
+    "migrations:check": "node tools/check-migrations.mjs",
     "test": "node --test tools/test-*.mjs"
   },
   "keywords": [