soturail 0.2.2 → 0.2.3

package/README.md

@@ -57,6 +57,17 @@ npm run release:full -- --version X.Y.Z
 
 The release script never runs `npm audit fix --force`, never publishes when build/tests/runtime audit fail and never creates a GitHub release before npm publish succeeds. See [docs/release-workflow.md](docs/release-workflow.md).
 
+## Release Reliability
+
+SotuRail includes a release preflight check to prevent stale package metadata, broken npm CLI binaries, missing release notes, and changelog/version mismatches.
+
+```bash
+npm run build
+npm test
+npm run release:check
+npm pack --dry-run
+```
+
 ## 2. Why SotuRail Exists
 
 AI coding agents often receive too much unstable context: full files, noisy test logs, repeated terminal output and long conversational summaries. SotuRail is designed to unify those workflows into one independent local-first tool without sending telemetry or inventing provider metrics.
@@ -88,7 +99,7 @@ Use directly with npx:
 
 ```bash
 npx soturail --help
-npx soturail@0.2.2 --help
+npx soturail@0.2.3 --help
 ```
 
 Install globally:
@@ -96,6 +107,7 @@ Install globally:
 ```bash
 npm install -g soturail
 soturail --help
+soturail --version
 ```
 
 For local development from source:
@@ -255,7 +267,7 @@ Windows users should see [docs/windows.md](docs/windows.md) for CMD vs PowerShel
 
 ## Road To Skill Rail
 
-Skill Rail and Workflow Rail are planned, not implemented in v0.2.2. See [docs/skill-rail.md](docs/skill-rail.md) and [docs/workflow-rail.md](docs/workflow-rail.md) for the security-first roadmap.
+Skill Rail and Workflow Rail are planned, not implemented in v0.2.x. See [docs/skill-rail.md](docs/skill-rail.md) and [docs/workflow-rail.md](docs/workflow-rail.md) for the security-first roadmap.
 
 ## Comparison Philosophy
 

package/dist/cli.js

@@ -19,12 +19,14 @@ import { registerRulesCommand } from "./commands/rules.js";
 import { registerSelfCommand } from "./commands/self.js";
 import { registerSpecCommand } from "./commands/spec.js";
 import { registerStatsCommand } from "./commands/stats.js";
+import { registerReleaseCommand } from "./commands/release.js";
+import { SOTURAIL_VERSION } from "./core/version.js";
 export function buildProgram() {
     const program = new Command();
     program
         .name("soturail")
         .description("Local-first Context OS rails for AI coding agents.")
-        .version("0.2.2")
+        .version(SOTURAIL_VERSION)
         .showHelpAfterError();
     registerInitCommand(program);
     registerIndexCommand(program);
@@ -40,6 +42,7 @@ export function buildProgram() {
     registerMemoryCommand(program);
     registerNativeCommand(program);
     registerRulesCommand(program);
+    registerReleaseCommand(program);
     registerSelfCommand(program);
     registerDoctorCommand(program);
     registerStatsCommand(program);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/release.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+export declare function registerReleaseCommand(program: Command): void;
+export declare function writeReleaseNotesSkeleton(version: string, root?: string): Promise<string>;

package/dist/commands/release.js

@@ -0,0 +1,59 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { formatReleasePreflight, runReleasePreflight } from "../core/release-preflight.js";
+export function registerReleaseCommand(program) {
+    const release = program
+        .command("release")
+        .description("Run local release reliability checks and release-note helpers.");
+    release
+        .command("check")
+        .description("Validate package, CLI, changelog, release notes, pack metadata and runtime audit.")
+        .action(async () => {
+        const result = await runReleasePreflight(process.cwd());
+        process.stdout.write(`${formatReleasePreflight(result)}\n`);
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+    release
+        .command("notes")
+        .description("Create a release notes skeleton for a version.")
+        .requiredOption("--version <version>", "Release version, for example X.Y.Z")
+        .action(async (options) => {
+        const filePath = await writeReleaseNotesSkeleton(options.version, process.cwd());
+        process.stdout.write(`Release notes written: ${path.relative(process.cwd(), filePath)}\n`);
+    });
+}
+export async function writeReleaseNotesSkeleton(version, root = process.cwd()) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`Invalid version: ${version}`);
+    }
+    const filePath = path.join(path.resolve(root), `RELEASE_NOTES_v${version}.md`);
+    const contents = `# SotuRail v${version} - Release Notes
+
+## Install
+
+    npx soturail@${version} --help
+    npm install -g soturail
+    soturail --help
+
+## Highlights
+
+- Update this section before publishing.
+
+## Validation
+
+- \`npm run build\`
+- \`npm test\`
+- \`npm audit --omit=dev\`
+- \`npm pack --dry-run\`
+- \`node dist/cli.js --version\`
+
+## Links
+
+- npm: https://www.npmjs.com/package/soturail
+- GitHub: https://github.com/Soturine/soturail
+`;
+    await fs.writeFile(filePath, contents, "utf8");
+    return filePath;
+}
+//# sourceMappingURL=release.js.map

package/dist/commands/release.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.js","sourceRoot":"","sources":["../../src/commands/release.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAE3F,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,MAAM,OAAO,GAAG,OAAO;SACpB,OAAO,CAAC,SAAS,CAAC;SAClB,WAAW,CAAC,gEAAgE,CAAC,CAAC;IAEjF,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,mFAAmF,CAAC;SAChG,MAAM,CAAC,KAAK,IAAI,EAAE;QACjB,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEL,OAAO;SACJ,OAAO,CAAC,OAAO,CAAC;SAChB,WAAW,CAAC,gDAAgD,CAAC;SAC7D,cAAc,CAAC,qBAAqB,EAAE,oCAAoC,CAAC;SAC3E,MAAM,CAAC,KAAK,EAAE,OAA4B,EAAE,EAAE;QAC7C,MAAM,QAAQ,GAAG,MAAM,yBAAyB,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACjF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0BAA0B,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7F,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,OAAe,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,EAAE;IACnF,IAAI,CAAC,qCAAqC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,kBAAkB,OAAO,KAAK,CAAC,CAAC;IAC/E,MAAM,QAAQ,GAAG,eAAe,OAAO;;;;mBAItB,OAAO;;;;;;;;;;;;;;;;;;;;CAoBzB,CAAC;IACA,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/C,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/core/release-preflight.d.ts

@@ -0,0 +1,22 @@
+export interface ReleaseGateResult {
+    id: string;
+    label: string;
+    ok: boolean;
+    required: boolean;
+    details: string;
+}
+export interface ReleasePreflightResult {
+    ok: boolean;
+    version: string | null;
+    packageName: string | null;
+    fullAuditDevOnly: boolean;
+    fullAuditFindings: string[];
+    gates: ReleaseGateResult[];
+}
+export interface ReleasePreflightOptions {
+    runAudit?: boolean;
+    runPack?: boolean;
+    cliCommand?: string[];
+}
+export declare function runReleasePreflight(root?: string, options?: ReleasePreflightOptions): Promise<ReleasePreflightResult>;
+export declare function formatReleasePreflight(result: ReleasePreflightResult): string;

package/dist/core/release-preflight.js

@@ -0,0 +1,199 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+export async function runReleasePreflight(root = process.cwd(), options = {}) {
+    const resolvedRoot = path.resolve(root);
+    const runAudit = options.runAudit ?? true;
+    const runPack = options.runPack ?? true;
+    const gates = [];
+    const packageJson = await readOptionalJson(path.join(resolvedRoot, "package.json"));
+    const packageName = typeof packageJson?.name === "string" ? packageJson.name : null;
+    const version = typeof packageJson?.version === "string" ? packageJson.version : null;
+    addGate(gates, "package_version", "package.json version", Boolean(version && SEMVER_PATTERN.test(version)), version ?? "missing");
+    const packageLock = await readOptionalJson(path.join(resolvedRoot, "package-lock.json"));
+    const lockVersion = typeof packageLock?.version === "string" ? packageLock.version : null;
+    const lockRootVersion = packageLock && typeof packageLock === "object"
+        && "packages" in packageLock
+        && packageLock.packages
+        && typeof packageLock.packages === "object"
+        && "" in packageLock.packages
+        && packageLock.packages[""]
+        && typeof packageLock.packages[""] === "object"
+        && "version" in packageLock.packages[""]
+        && typeof packageLock.packages[""].version === "string"
+        ? packageLock.packages[""].version
+        : null;
+    addGate(gates, "package_lock_version", "package-lock version sync", Boolean(version && lockVersion === version && lockRootVersion === version), `package-lock.version=${lockVersion ?? "missing"}, packages[\"\"].version=${lockRootVersion ?? "missing"}`);
+    const cliVersion = await readCliVersion(resolvedRoot, options.cliCommand);
+    addGate(gates, "cli_version", "CLI runtime version sync", Boolean(version && cliVersion.code === 0 && cliVersion.stdout.trim() === version), cliVersion.code === 0 ? `cli=${cliVersion.stdout.trim() || "empty"}, package=${version ?? "missing"}` : cliVersion.stderr.trim());
+    if (runPack) {
+        const pack = await runProcess("npm", ["pack", "--dry-run"], resolvedRoot, true);
+        const combined = `${pack.stdout}\n${pack.stderr}`;
+        const expectedTarball = packageName && version ? `${packageName}-${version}.tgz` : null;
+        addGate(gates, "npm_pack_metadata", "npm pack metadata", Boolean(pack.code === 0 && expectedTarball && combined.includes(expectedTarball)), expectedTarball ? `expected ${expectedTarball}` : "missing package name or version");
+    }
+    else {
+        addGate(gates, "npm_pack_metadata", "npm pack metadata", true, "skipped by test options", false);
+    }
+    const readme = await readOptionalText(path.join(resolvedRoot, "README.md"));
+    addGate(gates, "readme_install", "README install instructions", Boolean(readme && /npx\s+soturail/.test(readme) && readme.includes("npm install -g soturail") && readme.includes("soturail --version")), readme ? "README.md contains npm/npx/global install guidance" : "README.md missing");
+    const changelog = await readOptionalText(path.join(resolvedRoot, "CHANGELOG.md"));
+    addGate(gates, "changelog_entry", "CHANGELOG version entry", Boolean(version && changelog?.includes(`## [${version}]`)), version ? `expected ## [${version}]` : "missing version");
+    const releaseNotesPath = version ? path.join(resolvedRoot, `RELEASE_NOTES_v${version}.md`) : "";
+    addGate(gates, "release_notes", "release notes file", Boolean(version && existsSync(releaseNotesPath)), version ? path.relative(resolvedRoot, releaseNotesPath) : "missing version");
+    addGate(gates, "license", "LICENSE file", existsSync(path.join(resolvedRoot, "LICENSE")), "LICENSE");
+    let fullAudit = { total: 0, names: [] };
+    let runtimeAudit = { total: 0, names: [] };
+    if (runAudit) {
+        const runtime = await runProcess("npm", ["audit", "--omit=dev", "--json"], resolvedRoot, true);
+        runtimeAudit = parseAudit(runtime.stdout);
+        addGate(gates, "runtime_audit", "runtime npm audit", runtime.code === 0 && runtimeAudit.total === 0, runtimeAudit.total === 0 ? "0 runtime vulnerabilities" : `${runtimeAudit.total} runtime findings: ${runtimeAudit.names.join(", ")}`);
+        const full = await runProcess("npm", ["audit", "--json"], resolvedRoot, true);
+        fullAudit = parseAudit(full.stdout);
+    }
+    else {
+        addGate(gates, "runtime_audit", "runtime npm audit", true, "skipped by test options", false);
+    }
+    const fullAuditDevOnly = fullAudit.total === 0 || (runtimeAudit.total === 0 && fullAudit.total >= runtimeAudit.total);
+    addGate(gates, "full_audit_explained", "full npm audit explanation", fullAuditDevOnly, fullAudit.total === 0
+        ? "0 full audit findings"
+        : `${fullAudit.total} full audit findings treated as dev-only: ${fullAudit.names.join(", ")}`);
+    return {
+        ok: gates.every((gate) => !gate.required || gate.ok),
+        version,
+        packageName,
+        fullAuditDevOnly,
+        fullAuditFindings: fullAudit.names,
+        gates
+    };
+}
+export function formatReleasePreflight(result) {
+    const lines = [
+        `Release preflight: ${result.ok ? "passed" : "failed"}`,
+        `package: ${result.packageName ?? "unknown"}`,
+        `version: ${result.version ?? "unknown"}`,
+        `full_audit_dev_only: ${result.fullAuditDevOnly}`,
+        "gates:"
+    ];
+    for (const gate of result.gates) {
+        lines.push(`- ${gate.ok ? "PASS" : "FAIL"} ${gate.id}: ${gate.details}`);
+    }
+    return lines.join("\n");
+}
+async function readCliVersion(root, cliCommand) {
+    if (cliCommand && cliCommand.length > 0) {
+        const command = cliCommand[0];
+        const args = cliCommand.slice(1);
+        if (!command)
+            return { code: 1, stdout: "", stderr: "empty CLI command" };
+        return runProcess(command, args, root, true);
+    }
+    const cliPath = path.join(root, "dist", "cli.js");
+    if (!existsSync(cliPath)) {
+        return { code: 1, stdout: "", stderr: "dist/cli.js is missing; run npm run build first" };
+    }
+    return runProcess(process.execPath, [cliPath, "--version"], root, true);
+}
+async function readOptionalText(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+async function readOptionalJson(filePath) {
+    const text = await readOptionalText(filePath);
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function addGate(gates, id, label, ok, details, required = true) {
+    gates.push({ id, label, ok, details, required });
+}
+function parseAudit(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return {
+            total: parsed.metadata?.vulnerabilities?.total ?? 0,
+            names: Object.keys(parsed.vulnerabilities ?? {})
+        };
+    }
+    catch {
+        return { total: -1, names: [] };
+    }
+}
+async function runProcess(command, args, cwd, allowFailure = false) {
+    return new Promise((resolve, reject) => {
+        const spawnSpec = resolveSpawn(command, args);
+        const child = spawn(spawnSpec.command, spawnSpec.args, {
+            cwd,
+            shell: false,
+            windowsHide: true,
+            env: process.env
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const result = { code: code ?? 1, stdout, stderr };
+            if ((code ?? 1) !== 0 && !allowFailure) {
+                reject(new Error(`${command} ${args.join(" ")} failed with exit code ${code ?? 1}`));
+            }
+            else {
+                resolve(result);
+            }
+        });
+    });
+}
+function resolveSpawn(command, args) {
+    if (process.platform !== "win32")
+        return { command, args };
+    if (command === "npm" || command === "npx") {
+        const cli = npmCliPath(command);
+        if (cli)
+            return { command: process.execPath, args: [cli, ...args] };
+    }
+    if (command === "node")
+        return { command: process.execPath, args };
+    return { command: resolveWindowsCommand(command), args };
+}
+function npmCliPath(command) {
+    const npmExecPath = process.env.npm_execpath;
+    const candidates = [];
+    if (npmExecPath) {
+        const dir = path.dirname(npmExecPath);
+        candidates.push(path.resolve(dir, command === "npm" ? "npm-cli.js" : "npx-cli.js"));
+    }
+    const nodeDir = path.dirname(process.execPath);
+    candidates.push(path.resolve(nodeDir, "node_modules", "npm", "bin", command === "npm" ? "npm-cli.js" : "npx-cli.js"));
+    return candidates.find((candidate) => existsSync(candidate));
+}
+function resolveWindowsCommand(command) {
+    if (path.isAbsolute(command) && existsSync(command))
+        return command;
+    const extensions = path.extname(command) ? [""] : [".exe", ".cmd", ".bat", ""];
+    const entries = (process.env.PATH ?? "").split(path.delimiter).filter(Boolean);
+    for (const entry of entries) {
+        for (const extension of extensions) {
+            const candidate = path.resolve(entry, `${command}${extension}`);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return command;
+}
+//# sourceMappingURL=release-preflight.js.map

package/dist/core/release-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-preflight.js","sourceRoot":"","sources":["../../src/core/release-preflight.ts"],"names":[],"mappings":"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"}

package/dist/core/version.d.ts

@@ -0,0 +1 @@
+export declare const SOTURAIL_VERSION = "0.2.3";

package/dist/core/version.js

@@ -0,0 +1,3 @@
+// Generated by scripts/sync-version.mjs from package.json. Do not edit manually.
+export const SOTURAIL_VERSION = "0.2.3";
+//# sourceMappingURL=version.js.map

package/dist/core/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,gBAAgB,GAAG,OAAO,CAAC"}

package/docs/release-checklist.md

@@ -11,10 +11,22 @@ Before publishing:
 - [ ] `node dist/cli.js self all`
 - [ ] `npm pack --dry-run`
 - [ ] `npm run release:check`
+- [ ] `node dist/cli.js --version` matches `package.json`.
 - [ ] Confirm docs mention limitations honestly.
 - [ ] Confirm no telemetry exists.
 - [ ] Confirm no `git push` is routed through `soturail run`.
 
+## Version Sync
+
+Check four separate release identifiers before publishing:
+
+- npm package version: `package.json` and `package-lock.json`.
+- CLI runtime version: `node dist/cli.js --version`.
+- Git tag: created only when the release process calls for it.
+- GitHub release: created only after npm publish succeeds.
+
+The package version and CLI runtime version must match. `npm run build` regenerates the CLI version source from `package.json`, and `npm run release:check` verifies the built CLI before publication.
+
 ## Audit Distinction
 
 `npm audit` checks all dependencies, including dev dependencies used for local tests and builds.
@@ -23,7 +35,35 @@ Before publishing:
 
 Runtime audit is clean with `npm audit --omit=dev`. Remaining audit findings, if any, are development dependency findings and should be upgraded safely without `--force`.
 
-For v0.2.2, the full audit findings are in the Vitest/Vite development test stack. npm's suggested fix is a semver-major Vitest upgrade, so do not run `npm audit fix --force` blindly.
+For v0.2.x, the full audit findings are in the Vitest/Vite development test stack when present. npm's suggested fix may be a semver-major Vitest upgrade, so do not run `npm audit fix --force` blindly.
+
+## npm Login And 2FA
+
+Use browser-based npm login before publishing:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+If npm requires a one-time password during publish, provide a fresh authenticator code through `NPM_CONFIG_OTP` or `--otp`. Do not commit tokens, OTPs or npm credentials.
+
+PowerShell example:
+
+```powershell
+$env:NPM_CONFIG_OTP="<code>"
+npm run release:publish -- --version X.Y.Z
+Remove-Item Env:NPM_CONFIG_OTP
+```
+
+After npm publish succeeds, verify:
+
+```bash
+npm view soturail version
+npx --yes soturail@X.Y.Z --version
+```
+
+Create or update the GitHub release only after those npm checks pass.
 
 ## Windows Paste Safety
 

package/docs/release-workflow.md

@@ -10,6 +10,14 @@ npm run release:check
 
 Runs install, build, tests, runtime audit, self-dogfooding, pack dry-run and npm version checks. It also reports whether full audit findings are development-only.
 
+The check also verifies:
+
+- `package.json` and `package-lock.json` version sync;
+- `node dist/cli.js --version` matches the package version;
+- npm pack dry-run emits the matching tarball name;
+- `CHANGELOG.md` and `RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
+- README install instructions and `LICENSE` exist.
+
 ## Prepare
 
 ```bash
@@ -33,7 +41,22 @@ Prepare mode:
 npm run release:publish -- --version X.Y.Z
 ```
 
-Publish mode refuses to publish if build, tests or runtime audit fail, if the git tree is dirty, or if the version already exists on npm. If npm asks for 2FA or authentication, rerun the same command after completing the auth step.
+Publish mode refuses to publish if build, tests, release preflight or runtime audit fail, if the git tree is dirty, or if the version already exists on npm.
+
+For browser-based npm login:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+If npm asks for 2FA during publish, use a fresh authenticator code:
+
+```powershell
+$env:NPM_CONFIG_OTP="<code>"
+npm run release:publish -- --version X.Y.Z
+Remove-Item Env:NPM_CONFIG_OTP
+```
 
 ## Full
 
@@ -43,6 +66,13 @@ npm run release:full -- --version X.Y.Z
 
 Full mode runs prepare, publish and then creates or updates the GitHub release using `gh` when available. If the npm version already exists, full mode skips npm publish and only creates or updates the GitHub release.
 
+Only create or update the GitHub release after npm publish succeeds and these checks pass:
+
+```bash
+npm view soturail version
+npx --yes soturail@X.Y.Z --version
+```
+
 Safety rules:
 
 - Never run `npm audit fix --force`.

package/docs/skill-rail.md

@@ -1,6 +1,6 @@
 # Skill Rail
 
-Skill Rail is planned for v0.3.0. It is not implemented in v0.2.2.
+Skill Rail is planned for v0.3.0. It is not implemented in v0.2.x.
 
 The goal is to turn approved SotuRail specs, rules and workflows into portable, reviewable agent skills without installing untrusted marketplace content automatically.
 

package/docs/windows.md

@@ -26,7 +26,7 @@ From a source checkout:
 npm run build
 npm pack --dry-run
 npm pack
-npm install -g .\soturail-0.2.1.tgz
+npm install -g .\soturail-0.2.3.tgz
 soturail --version
 ```
 
@@ -74,3 +74,24 @@ npx soturail --help
 ## Safety
 
 SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.
+
+## Release Checks On Windows
+
+Before publishing from Windows, run:
+
+```powershell
+npm run build
+node .\dist\cli.js --version
+npm run release:check
+```
+
+`package.json`, `package-lock.json`, `node dist/cli.js --version`, the npm tarball name, the changelog and the release notes must all agree on the same version.
+
+Use browser-based npm login when needed:
+
+```powershell
+npm login --auth-type=web
+npm whoami
+```
+
+Only create the GitHub release after npm publish succeeds and `npx --yes soturail@X.Y.Z --version` prints the published version.

package/docs/workflow-rail.md

@@ -1,6 +1,6 @@
 # Workflow Rail
 
-Workflow Rail is planned for v0.4.0. It is not implemented in v0.2.2.
+Workflow Rail is planned for v0.4.0. It is not implemented in v0.2.x.
 
 The goal is to describe repeatable engineering workflows as local, auditable artifacts that can later export into Skill Rail or an MCP server.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Local-first context rails for AI coding agents: reversible terminal compression, progressive repo reading, SDD workflows, hooks, benchmarks, memory and cache-friendly payloads.",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "sync:version": "node scripts/sync-version.mjs",
+    "build": "npm run sync:version && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",