@jstn-sdk/ma 0.1.2 → 0.1.4

package/README.md

@@ -10,9 +10,9 @@
 </div>
 
 > [!IMPORTANT]
-> Meta-Architect `v0.1.2` is a production-grade skills line.
+> Meta-Architect `v0.1.4` is a production-grade skills line.
 > It is not a lightweight demo branch.
-> From `v0.1.2` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
+> From `v0.1.4` onward, the package is expected to ship with stable skill contracts, deterministic packaging, explicit release gates, and honest install and publish surfaces.
 
 ## Overview
 
@@ -44,7 +44,7 @@ It adds:
   </tr>
   <tr>
     <td><strong>Release line</strong></td>
-    <td><code>v0.1.2</code></td>
+    <td><code>v0.1.4</code></td>
   </tr>
   <tr>
     <td><strong>License</strong></td>
@@ -193,7 +193,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.2
+8. Delivery plan for v0.1.4
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this
@@ -447,6 +447,12 @@ Provenance note:
 - a local shell publish will fail with `Automatic provenance generation not supported for provider: null`
 - use the repository publish workflow when provenance is required
 
+Release automation:
+- `npm run release:sync` bumps and synchronizes the active release line only when watched release-relevant files changed
+- `npm run release:advance` force-bumps the next patch line and rewrites the same version-bearing files
+- `.github/workflows/release-sync.yml` runs the sync path on `main` pushes that touch watched release-relevant paths
+- `.github/workflows/release-advance.yml` runs after a published GitHub release and advances the repo to the next patch line automatically
+
 > [!CAUTION]
 > Do not claim npm, GitHub release, or any other publish channel until that channel has actually succeeded.
 > Release documentation must match reality, not intent.
@@ -517,7 +523,7 @@ Provenance note:
 | [Plugin README](./plugins/meta-architect/README.md) | plugin distribution surface |
 | [Collaborative Whiteboard Mission](./missions/collaborative-whiteboard/mission.md) | concrete scenario walkthrough |
 | [Release Spec](./docs/release-spec.md) | release and gate policy |
-| [Release Readiness](./docs/qa/release-readiness-0.1.2.md) | QA evidence for the `v0.1.2` line |
+| [Release Readiness](./docs/qa/release-readiness-0.1.4.md) | QA evidence for the `v0.1.4` line |
 
 ## Release Hygiene
 

package/docs/README.md

@@ -17,7 +17,7 @@ Meta-Architect documentation is organized by operator task.
 
 ## QA and readiness
 
-- [Release Readiness 0.1.2](./qa/release-readiness-0.1.2.md)
+- [Release Readiness 0.1.4](./qa/release-readiness-0.1.4.md)
 
 ## Repo structure references
 

package/docs/getting-started.md

@@ -74,7 +74,7 @@ Required output:
 5. Data model and storage choices
 6. Auth/security considerations
 7. DX/UX considerations
-8. Delivery plan for v0.1.2
+8. Delivery plan for v0.1.4
 9. Risks and trade-offs
 10. Decision log
 11. Exact next trigger to run after this

package/docs/qa/{release-readiness-0.1.2.md → release-readiness-0.1.4.md}

@@ -1,25 +1,25 @@
-# Release Readiness 0.1.2
+# Release Readiness 0.1.4
 
 ## Production bar
 
-`v0.1.2` is treated as production only when:
+`v0.1.4` is treated as production only when:
 - the package installs cleanly from the canonical public install command
 - the Codex-hosted runtime path works end to end
 - the helper flow remains valid for scripted verification
-- release docs, package metadata, and workflows all agree on `0.1.2`
+- release docs, package metadata, and workflows all agree on `0.1.4`
 
 Target release state:
-- npm package: `@jstn-sdk/ma@0.1.2`
+- npm package: `@jstn-sdk/ma@0.1.4`
 - npm registry state: pending publish
-- publishability note: `0.1.1` is already published, so `0.1.2` is the next publishable package line
-- git tag: `v0.1.2`
-- GitHub release: pending publish for `v0.1.2`
+- publishability note: `0.1.3` is already published, so `0.1.4` is the next publishable package line
+- git tag: `v0.1.4`
+- GitHub release: pending publish for `v0.1.4`
 
 ## Production checklist
 
 - skills-first product identity: PASS
 - package/plugin identity aligned to `@jstn-sdk/ma`: PASS
-- version/tag alignment `0.1.2` / `v0.1.2`: PASS
+- version/tag alignment `0.1.4` / `v0.1.4`: PASS
 - install/uninstall docs aligned: PASS
 - onboarding is concise and sequential: PASS
 - helper command documented as secondary: PASS

package/docs/release-spec.md

@@ -1,13 +1,13 @@
-# v0.1.2 Requirements & Rules
+# v0.1.4 Requirements & Rules
 
 ## Production definition
 
-Meta-Architect `v0.1.2` is production only when:
+Meta-Architect `v0.1.4` is production only when:
 1. the package/install surface works
 2. the in-session skill workflow from `$arch` through `$build` works
 3. the release evidence matches the actual package and git tag
 
-## What `v0.1.2` must have
+## What `v0.1.4` must have
 
 ### 1. Canonical package/runtime path
 
@@ -49,11 +49,11 @@ Canonical state files:
 
 ### 4. Required release evidence
 
-- `package.json` version `0.1.2`
-- git tag `v0.1.2`
+- `package.json` version `0.1.4`
+- git tag `v0.1.4`
 - `RELEASE.md`
 - `CHANGELOG.md`
-- `docs/qa/release-readiness-0.1.2.md`
+- `docs/qa/release-readiness-0.1.4.md`
 - green `npm run release:check`
 
 ### 5. Dist-tag discipline
@@ -79,6 +79,13 @@ Canonical state files:
    - Prerelease publish: `npm publish --access public --tag <lane>`
 10. Verify dist-tags with `npm view @jstn-sdk/ma version dist-tags time --json`
 
+### 6.1 Release automation
+
+- `npm run release:sync` updates the active release line when watched release-relevant files changed
+- `npm run release:advance` force-bumps the next patch line after a completed release
+- `.github/workflows/release-sync.yml` automates the sync path on `main`
+- `.github/workflows/release-advance.yml` advances the repo to the next patch line after a published release
+
 ### 7. Provenance rule
 
 - `npm publish --provenance` is valid only from a supported cloud CI/CD provider

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jstn-sdk/ma",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Codex-native skills system for architecture, evidence, review, and gated build guidance.",
   "license": "MIT",
   "author": "JustineDevs",
@@ -60,6 +60,8 @@
     "status": "node ./bin/ma.js status",
     "build:gate": "node ./bin/ma.js run '$build'",
     "release:meta": "node ./scripts/release-metadata.js",
+    "release:sync": "node ./scripts/release-sync.js",
+    "release:advance": "node ./scripts/release-sync.js --force --bump patch",
     "release:verify": "node ./scripts/release-verify.js",
     "release:check": "npm run release:verify && npm run skills:manifest && npm run plugin:sync && npm run skills:validate && npm run plugin:verify && npm run skills:pack && npm run check && npm test && npm run pack:inspect",
     "skills:manifest": "node ./scripts/skills-manifest.js",

package/plugins/meta-architect/.app.json

@@ -1,7 +1,7 @@
 {
   "name": "meta-architect",
   "displayName": "Meta-Architect",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Programmatic architecture and verified engineering skills for Codex-native workflows.",
   "entry": "./README.md",
   "skillsDir": "./skills"

package/plugins/meta-architect/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Skills-first workflow layer for Codex with architecture, evidence, review, and gated build guidance.",
   "author": {
     "name": "JustineDevs",

package/plugins/meta-architect/.mcp.json

@@ -1,6 +1,6 @@
 {
   "name": "meta-architect",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "collections": [
     "sindresorhus/awesome",
     "dzharii/awesome-typescript",

package/plugins/meta-architect/README.md

@@ -105,7 +105,7 @@ When consuming the plugin:
 The plugin version should track the release scope of the core repo.
 
 For this repository:
-- plugin scope is aligned to Meta-Architect `v0.1.2`
+- plugin scope is aligned to Meta-Architect `v0.1.4`
 - any breaking contract change should be versioned intentionally
 
 The plugin is one distribution surface of the same product, not a separate product line.

package/scripts/release-sync.js

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const WATCHED_PREFIXES = [
+  "bin/",
+  "docs/",
+  "example/",
+  "mcp/",
+  "missions/",
+  "plugins/",
+  "prompts/",
+  ".codex/prompts/",
+  "sprint/",
+  "templates/",
+  "src/",
+  "skills/",
+];
+
+const WATCHED_FILES = new Set([
+  "README.md",
+  "RELEASE.md",
+  "CHANGELOG.md",
+  "package.json",
+  "package-lock.json",
+]);
+
+function parseArgs(argv) {
+  const args = {
+    bump: "",
+    fromRef: "",
+    toRef: "",
+    githubOutput: "",
+    force: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--bump") {
+      args.bump = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--from-ref") {
+      args.fromRef = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--to-ref") {
+      args.toRef = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--github-output") {
+      args.githubOutput = argv[index + 1] ?? "";
+      index += 1;
+      continue;
+    }
+    if (token === "--force") {
+      args.force = true;
+    }
+  }
+
+  return args;
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeJson(file, value) {
+  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function readText(file) {
+  return fs.readFileSync(file, "utf8");
+}
+
+function writeText(file, content) {
+  fs.writeFileSync(file, content);
+}
+
+function replaceRequired(text, search, replacement, label) {
+  if (!text.includes(search)) {
+    throw new Error(`Expected to find ${label}: ${search}`);
+  }
+  return text.replaceAll(search, replacement);
+}
+
+function parseVersion(version) {
+  const match = version.match(/^(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)$/);
+  if (!match?.groups) {
+    throw new Error(`Unsupported version for release-sync: ${version}`);
+  }
+  return {
+    major: Number(match.groups.major),
+    minor: Number(match.groups.minor),
+    patch: Number(match.groups.patch),
+  };
+}
+
+function bumpVersion(version, bumpKind) {
+  const parsed = parseVersion(version);
+  if (bumpKind === "major") {
+    return `${parsed.major + 1}.0.0`;
+  }
+  if (bumpKind === "minor") {
+    return `${parsed.major}.${parsed.minor + 1}.0`;
+  }
+  return `${parsed.major}.${parsed.minor}.${parsed.patch + 1}`;
+}
+
+function git(args) {
+  return execFileSync("git", args, { encoding: "utf8" }).trim();
+}
+
+function getChangedFiles({ fromRef, toRef, force }) {
+  if (process.env.RELEASE_SYNC_CHANGED_FILES) {
+    return process.env.RELEASE_SYNC_CHANGED_FILES.split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  if (force) {
+    return [];
+  }
+
+  if (fromRef && toRef && !/^0+$/.test(fromRef)) {
+    return git(["diff", "--name-only", fromRef, toRef])
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean);
+  }
+
+  return git(["status", "--porcelain"])
+    .split("\n")
+    .map((line) => line.slice(3).trim())
+    .filter(Boolean);
+}
+
+function isWatchedPath(file) {
+  return WATCHED_FILES.has(file) || WATCHED_PREFIXES.some((prefix) => file.startsWith(prefix));
+}
+
+function prependChangelog(version) {
+  const changelogPath = "CHANGELOG.md";
+  const changelog = readText(changelogPath);
+  if (changelog.includes(`## v${version}`)) {
+    return;
+  }
+
+  const next = changelog.replace(
+    "# Changelog\n\n",
+    `# Changelog\n\n## v${version}\n\n- Release line prepared automatically for v${version}.\n\n`,
+  );
+  writeText(changelogPath, next);
+}
+
+function updateCurrentSurfaceFile(file, oldVersion, nextVersion) {
+  const oldTag = `v${oldVersion}`;
+  const nextTag = `v${nextVersion}`;
+  const oldQa = `release-readiness-${oldVersion}.md`;
+  const nextQa = `release-readiness-${nextVersion}.md`;
+  let content = readText(file);
+  if (content.includes(oldTag)) {
+    content = content.replaceAll(oldTag, nextTag);
+  }
+  if (content.includes(oldVersion)) {
+    content = content.replaceAll(oldVersion, nextVersion);
+  }
+  content = content.replaceAll(oldQa, nextQa);
+  writeText(file, content);
+}
+
+function syncPackageVersion(nextVersion) {
+  const pkg = readJson("package.json");
+  const lock = readJson("package-lock.json");
+  pkg.version = nextVersion;
+  lock.version = nextVersion;
+  if (lock.packages?.[""]) {
+    lock.packages[""].version = nextVersion;
+  }
+  writeJson("package.json", pkg);
+  writeJson("package-lock.json", lock);
+}
+
+function syncPluginVersions(nextVersion) {
+  for (const file of [
+    path.join("plugins", "meta-architect", ".app.json"),
+    path.join("plugins", "meta-architect", ".mcp.json"),
+    path.join("plugins", "meta-architect", ".codex-plugin", "plugin.json"),
+  ]) {
+    const value = readJson(file);
+    value.version = nextVersion;
+    writeJson(file, value);
+  }
+}
+
+function syncCurrentReleaseFiles(oldVersion, nextVersion) {
+  for (const file of [
+    "README.md",
+    "RELEASE.md",
+    path.join("docs", "README.md"),
+    path.join("docs", "getting-started.md"),
+    path.join("docs", "release-spec.md"),
+    path.join("plugins", "meta-architect", "README.md"),
+  ]) {
+    updateCurrentSurfaceFile(file, oldVersion, nextVersion);
+  }
+
+  const oldQa = path.join("docs", "qa", `release-readiness-${oldVersion}.md`);
+  const nextQa = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
+  fs.renameSync(oldQa, nextQa);
+  updateCurrentSurfaceFile(nextQa, oldVersion, nextVersion);
+}
+
+function syncSupportingCode(oldVersion, nextVersion) {
+  const replacements = [
+    {
+      file: path.join("src", "skills.js"),
+      search: `release-readiness-${oldVersion}.md`,
+      replacement: `release-readiness-${nextVersion}.md`,
+      label: "skills QA path",
+    },
+    {
+      file: path.join("src", "mcp-live-client.js"),
+      search: `version: "${oldVersion}"`,
+      replacement: `version: "${nextVersion}"`,
+      label: "mcp live client version",
+    },
+    {
+      file: path.join("test", "package-install-smoke.test.js"),
+      search: `jstn-sdk-ma-${oldVersion}.tgz`,
+      replacement: `jstn-sdk-ma-${nextVersion}.tgz`,
+      label: "tarball filename",
+    },
+    {
+      file: path.join("test", "policy.test.js"),
+      search: `release/${oldVersion}`,
+      replacement: `release/${nextVersion}`,
+      label: "release branch example",
+    },
+  ];
+
+  for (const entry of replacements) {
+    const content = readText(entry.file);
+    writeText(entry.file, replaceRequired(content, entry.search, entry.replacement, entry.label));
+  }
+}
+
+function rewriteReleaseState(nextVersion, previousVersion) {
+  const releasePath = "RELEASE.md";
+  const qaPath = path.join("docs", "qa", `release-readiness-${nextVersion}.md`);
+
+  let release = readText(releasePath);
+  release = release.replace(
+    /- npm package: `@jstn-sdk\/ma@[0-9]+\.[0-9]+\.[0-9]+`/,
+    `- npm package: \`@jstn-sdk/ma@${nextVersion}\``,
+  );
+  release = release.replace(
+    /- publishability note: .+/,
+    `- publishability note: \`${previousVersion}\` is already published, so \`${nextVersion}\` is the next publishable package line`,
+  );
+  release = release.replace(
+    /- GitHub release: .+/,
+    `- GitHub release: pending publish for \`v${nextVersion}\``,
+  );
+  release = release.replace(
+    /- npm publication has not been run yet for `@jstn-sdk\/ma@[0-9]+\.[0-9]+\.[0-9]+`/,
+    `- npm publication has not been run yet for \`@jstn-sdk/ma@${nextVersion}\``,
+  );
+  writeText(releasePath, release);
+
+  let qa = readText(qaPath);
+  qa = qa.replace(
+    /- npm package: `@jstn-sdk\/ma@[0-9]+\.[0-9]+\.[0-9]+`/,
+    `- npm package: \`@jstn-sdk/ma@${nextVersion}\``,
+  );
+  qa = qa.replace(
+    /- publishability note: .+/,
+    `- publishability note: \`${previousVersion}\` is already published, so \`${nextVersion}\` is the next publishable package line`,
+  );
+  qa = qa.replace(
+    /- GitHub release: .+/,
+    `- GitHub release: pending publish for \`v${nextVersion}\``,
+  );
+  writeText(qaPath, qa);
+}
+
+function writeGithubOutput(outputPath, { updated, version }) {
+  const lines = [`updated=${updated}`, `version=${version}`];
+  fs.appendFileSync(outputPath, `${lines.join("\n")}\n`);
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const pkg = readJson("package.json");
+  const currentVersion = pkg.version;
+  const changedFiles = getChangedFiles(args);
+  const relevantChanges = args.force ? ["<forced>"] : changedFiles.filter(isWatchedPath);
+
+  if (relevantChanges.length === 0 && !args.force) {
+    if (args.githubOutput) {
+      writeGithubOutput(args.githubOutput, { updated: "false", version: currentVersion });
+    }
+    console.log(
+      JSON.stringify(
+        {
+          updated: false,
+          forced: false,
+          version: currentVersion,
+          changedFiles,
+        },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  const bumpKind = args.bump || "patch";
+  const nextVersion = bumpVersion(currentVersion, bumpKind);
+
+  syncPackageVersion(nextVersion);
+  syncPluginVersions(nextVersion);
+  prependChangelog(nextVersion);
+  syncCurrentReleaseFiles(currentVersion, nextVersion);
+  syncSupportingCode(currentVersion, nextVersion);
+  rewriteReleaseState(nextVersion, currentVersion);
+
+  if (args.githubOutput) {
+    writeGithubOutput(args.githubOutput, { updated: "true", version: nextVersion });
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        updated: true,
+        forced: args.force,
+        bump: bumpKind,
+        previousVersion: currentVersion,
+        version: nextVersion,
+        changedFiles: relevantChanges,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}

package/src/mcp-live-client.js

@@ -38,7 +38,7 @@ export class McpSseClient {
       capabilities: {},
       clientInfo: {
         name: "meta-architect",
-        version: "0.1.2",
+        version: "0.1.4",
       },
     });
 

package/src/skills.js

@@ -344,8 +344,8 @@ export async function runInit() {
       path.join(getRepoRoot(), "docs", "release-spec.md"),
     ],
     [
-      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.2.md"),
-      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.2.md"),
+      path.join(packageRoot, "docs", "qa", "release-readiness-0.1.4.md"),
+      path.join(getRepoRoot(), "docs", "qa", "release-readiness-0.1.4.md"),
     ],
   ];