@warnyin/sdlc 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.10.0 (2026-09-14)
+
+- **Feature (update notice)**: a project is now told when a newer `@warnyin/sdlc` exists. Once a
+  day the SessionStart hook hands a background process one request to the npm registry for the
+  `latest` version; the session never waits on it. When the installed version (recorded in the
+  new `sdlc/.hooks/version.json`) is older, the next session's context opens with one line
+  naming both versions and `npx @warnyin/sdlc@latest update`, and telling the agent to mention
+  it and not run it. It repeats at every session start (including resume and `/clear`) until
+  the project is updated or the check is off. Nothing updates by itself. Only a plain `X.Y.Z` from the registry is ever cached
+  or shown; redirects, bodies over 64 KiB and anything slow or broken leave silence. **Existing
+  installs are on by default** after `update`, because `update` never rewrites your
+  `sdlc/config.yaml`: add `updateCheck: false` there to switch it off, or set `CI` or
+  `NO_UPDATE_NOTIFIER`. Behind a proxy the check stays silent (Node's fetch ignores
+  `HTTPS_PROXY`). Claude Code only; other tools install no hooks. `update` now always rewrites
+  `sdlc/.hooks/version.json`, even where your other hook files are kept.
+- **Release**: versions are now published by GitHub Actions from a pushed `vX.Y.Z` tag through
+  npm trusted publishing, with a provenance attestation that links each tarball to its commit
+  and workflow run. No npm token is involved.
+
 ## 0.9.0 (2026-09-14)
 
 - **Feature (new)**: `/sdlc:new` now asks its clarifying questions in rounds that follow

package/README.md

@@ -89,4 +89,30 @@ This repo self-hosts: its own development flows through `sdlc/changes/`. After c
 `npm run setup:dogfood` to regenerate the installer-owned mirrors (`sdlc/.playbook/`,
 `sdlc/.hooks/`, `.claude/`).
 
+## Releasing
+
+Pushing a plain `vX.Y.Z` tag publishes that version. `.github/workflows/release.yml` runs the CI
+jobs as a gate, checks the tag names `package.json`'s version, then runs `npm publish` with
+provenance through npm trusted publishing. No npm token lives in the repo or its secrets.
+
+One-time setup, by a package owner, before the first release tag is pushed (until then the
+publish step fails and nothing is released):
+1. On npmjs.com, open `@warnyin/sdlc` → Settings → Trusted Publisher → GitHub Actions and enter
+   organization/user `warnyin`, repository `warnyin-sdlc`, workflow filename `release.yml`,
+   no environment. If asked which actions to allow, allow `npm publish`, not stage-only.
+2. Optional, after the first release by tag succeeds: under Publishing access, choose
+   "Require two-factor authentication and disallow tokens".
+3. On GitHub, add a tag ruleset for `v*` so only maintainers can create or move release tags —
+   whoever can push the tag can publish.
+
+Each release:
+1. Bump `version` in `package.json`, add the `CHANGELOG.md` entry, commit `chore(release): X.Y.Z`.
+2. `git tag vX.Y.Z && git push origin main vX.Y.Z`
+3. Watch the `release` run in GitHub Actions, then confirm with `npm view @warnyin/sdlc version`.
+
+A tag that disagrees with `package.json`, a pre-release tag, a tag not on `main`, or a red gate
+publishes nothing. Every release becomes `latest`, so cut releases from `main` only. A published
+version can never be reused: to back one out, `npm deprecate @warnyin/sdlc@X.Y.Z "<reason>"` and
+release a fixed X.Y.Z+1.
+
 MIT

package/bin/cli.mjs

@@ -230,6 +230,18 @@ function scaffoldSdlc(projectRoot, tools, ctx) {
   copyTree(path.join(PAYLOAD, 'templates'), path.join('sdlc', '.playbook', 'templates'), projectRoot, ctx);
   copyTree(path.join(PAYLOAD, 'hooks'), path.join('sdlc', '.hooks'), projectRoot, ctx);
   copyTree(path.join(PKG_ROOT, 'lib'), path.join('sdlc', '.hooks', 'lib'), projectRoot, ctx);
+  recordPayloadVersion(projectRoot, ctx);
+}
+
+// The hooks carry no package.json; the update notice compares against this. It is a record
+// the CLI writes, not a user file, so it is rewritten every run instead of going through
+// installFile's keep-if-different rule — otherwise a hand edit, or a clone whose gitignored
+// manifest is missing, would freeze it and the notice would repeat after every update.
+function recordPayloadVersion(projectRoot, ctx) {
+  const rel = path.join('sdlc', '.hooks', 'version.json');
+  const content = `${JSON.stringify({ version: pkgVersion() })}\n`;
+  writeFileNormalized(path.join(projectRoot, rel), content);
+  ctx.manifest.set(toPosix(rel), sha256(content));
 }
 
 export function writeManifestFile(projectRoot, manifest) {

package/lib/update-notice.mjs

@@ -0,0 +1,42 @@
+// Pure decisions for the update notice: whether to check, whether a check is due, and the
+// line to show. No fs, no network — the SessionStart hook and the detached checker own I/O.
+
+import { parseVersion, compareVersions } from './version.mjs';
+
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+export const PACKAGE_NAME = '@warnyin/sdlc';
+export const CHECK_INTERVAL_MS = 24 * 3600_000;
+export const FETCH_TIMEOUT_MS = 3000;
+export const MAX_BODY_BYTES = 64 * 1024;
+
+const OFF_VALUES = new Set(['false', 'no', 'off', '0']);
+const set = (v) => typeof v === 'string' && v !== '';
+
+const unquote = (v) => String(v ?? '').trim().replace(/^(['"])(.*)\1$/, '$2').toLowerCase();
+
+// `CI=false` / `CI=0` are how some runners say "not CI"; any other non-empty CI means CI.
+export function isCheckDisabled(env = {}, config = {}) {
+  if (OFF_VALUES.has(unquote(config.updateCheck))) return true;
+  if (set(env.NO_UPDATE_NOTIFIER)) return true;
+  return set(env.CI) && !OFF_VALUES.has(env.CI.toLowerCase());
+}
+
+// Missing, unparsable or future timestamps are stale: a clock that jumped back must not
+// silence the check until real time catches up.
+export function isCheckDue(cache, now) {
+  const at = Date.parse(cache?.checkedAt);
+  if (Number.isNaN(at) || at > now) return true;
+  return now - at >= CHECK_INTERVAL_MS;
+}
+
+export function latestUrl(base) {
+  return `${String(base).replace(/\/+$/, '')}/${PACKAGE_NAME.replace('/', '%2F')}/latest`;
+}
+
+export function noticeLine(installed, latest) {
+  if (!parseVersion(installed) || !parseVersion(latest)) return null;
+  if (!(compareVersions(latest, installed) > 0)) return null;
+  // `@latest`: a bare `npx <pkg>` may resolve a local or cached copy and update to nothing.
+  return `[sdlc] ${PACKAGE_NAME} ${latest} is available (this project has ${installed}). Tell the user once; `
+    + `they can run \`npx ${PACKAGE_NAME}@latest update\` — do not run it yourself.`;
+}

package/lib/version.mjs

@@ -0,0 +1,23 @@
+// Strict plain `X.Y.Z` versions. The update notice prints only what passes parseVersion, so
+// this regex is the whole boundary between registry-supplied text and the agent's context:
+// no pre-release, no build metadata, no leading zeros, at most 9 digits per part.
+
+const PLAIN_VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+
+export function parseVersion(value) {
+  if (typeof value !== 'string') return null;
+  const m = value.match(PLAIN_VERSION);
+  return m ? m.slice(1).map(Number) : null;
+}
+
+// Negative, zero or positive like a sort comparator; NaN when either side is not a plain
+// version, so `compareVersions(a, b) > 0` is false for anything unparsable.
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return NaN;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+  }
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warnyin/sdlc",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Spec-driven, AI-driven SDLC framework — token-lean specs, contract-first changes, autonomous pipeline with managed hooks. Operationalizes the Day-1 'New SDLC with Vibe Coding' work process.",
   "type": "module",
   "bin": {

package/payload/hooks/_update-notice.mjs

@@ -0,0 +1,81 @@
+// SessionStart side of the update notice: reads the cached check, and when it is due records
+// the attempt and hands the network request to a detached `check-update.mjs`. Never waits on
+// the network and never throws — any failure means no notice.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { parseConfig } from './lib/config.mjs';
+import { parseVersion } from './lib/version.mjs';
+import { isCheckDisabled, isCheckDue, noticeLine } from './lib/update-notice.mjs';
+
+export const cachePath = (sdlcRoot) => path.join(sdlcRoot, '.state', 'update-check.json');
+
+export function readJsonFile(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+}
+
+// `.state/` is gitignored, not unwritable: a repo can ship a link there. Write only into a
+// `.state/` that already exists and really is `<sdlcRoot>/.state` (same rule as the change
+// pointers in lib/active.mjs); never create it, so a deleted project is not resurrected.
+function isRealStateDir(sdlcRoot) {
+  try {
+    const stateDir = path.join(sdlcRoot, '.state');
+    return fs.lstatSync(stateDir).isDirectory()
+      && fs.realpathSync.native(stateDir) === path.join(fs.realpathSync.native(sdlcRoot), '.state');
+  } catch {
+    return false;
+  }
+}
+
+// Temp file + rename: a symlink at the destination is replaced rather than written through,
+// and a concurrent reader sees the old file or the new one, never half of either.
+export function writeCache(sdlcRoot, value) {
+  const p = cachePath(sdlcRoot);
+  if (!isRealStateDir(sdlcRoot)) return false;
+  const tmp = `${p}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(value), { flag: 'wx' });
+    fs.renameSync(tmp, p);
+    return true;
+  } catch {
+    fs.rmSync(tmp, { force: true });
+    return false;
+  }
+}
+
+function readConfig(sdlcRoot) {
+  try { return parseConfig(fs.readFileSync(path.join(sdlcRoot, 'config.yaml'), 'utf8')); } catch { return {}; }
+}
+
+// The checker talks to a third-party host; it gets only what a request needs, not the
+// session's tokens. SYSTEMROOT keeps Windows sockets working; the CA var keeps corporate TLS.
+const CHECKER_ENV = ['PATH', 'SYSTEMROOT', 'NODE_EXTRA_CA_CERTS', 'WARNYIN_SDLC_REGISTRY_URL'];
+const checkerEnv = (env) => Object.fromEntries(CHECKER_ENV.filter((k) => env[k] !== undefined).map((k) => [k, env[k]]));
+
+function startCheck(hooksDir) {
+  const child = spawn(process.execPath, [path.join(hooksDir, 'check-update.mjs')], {
+    detached: true, stdio: 'ignore', windowsHide: true, env: checkerEnv(process.env),
+  });
+  child.on('error', () => {});
+  child.unref();
+}
+
+export function updateNotice({ sdlcRoot, hooksDir, now = Date.now() }) {
+  try {
+    if (isCheckDisabled(process.env, readConfig(sdlcRoot))) return null;
+    const installed = readJsonFile(path.join(hooksDir, 'version.json'))?.version;
+    if (!parseVersion(installed)) return null;
+    const cache = readJsonFile(cachePath(sdlcRoot));
+    const latest = parseVersion(cache?.latest) ? cache.latest : undefined;
+    // No recorded attempt, no request: a cache that cannot be written would otherwise mean a
+    // request on every session.
+    if (isCheckDue(cache, now) && writeCache(sdlcRoot, { checkedAt: new Date(now).toISOString(), latest })) {
+      startCheck(hooksDir);
+    }
+    return noticeLine(installed, latest);
+  } catch {
+    return null;
+  }
+}

package/payload/hooks/check-update.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// Detached from SessionStart by _update-notice.mjs — not a registered hook. Asks the registry
+// for the latest published version and caches it only when it is a plain X.Y.Z. Prints
+// nothing, follows no redirect, reads at most MAX_BODY_BYTES, and gives up after
+// FETCH_TIMEOUT_MS. Every failure leaves the cache as the hook left it.
+
+import process from 'node:process';
+import { resolveRoots } from './_shared.mjs';
+import { cachePath, readJsonFile, writeCache } from './_update-notice.mjs';
+import { parseVersion } from './lib/version.mjs';
+import {
+  DEFAULT_REGISTRY, FETCH_TIMEOUT_MS, MAX_BODY_BYTES, latestUrl,
+} from './lib/update-notice.mjs';
+
+const { sdlcRoot } = resolveRoots(import.meta.url);
+
+async function readCapped(body, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of body) {
+    size += typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.byteLength;
+    if (size > limit) return null;
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function main() {
+  const url = new URL(latestUrl(process.env.WARNYIN_SDLC_REGISTRY_URL || DEFAULT_REGISTRY));
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') return; // fetch also reads data:
+  const res = await fetch(url, {
+    redirect: 'error',
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+  });
+  if (!res.ok || !res.body) return;
+  const text = await readCapped(res.body, MAX_BODY_BYTES);
+  if (text === null) return;
+  const version = JSON.parse(text)?.version;
+  if (!parseVersion(version)) return;
+  const cache = readJsonFile(cachePath(sdlcRoot));
+  writeCache(sdlcRoot, { checkedAt: cache?.checkedAt ?? new Date().toISOString(), latest: version });
+}
+
+main().catch(() => {}).finally(() => process.exit(0)); // fail open, silently

package/payload/hooks/inject-context.mjs

@@ -2,7 +2,8 @@
 // SessionStart hook — THE static-context loader. Emits (hard cap 60 lines):
 //   constitution + every `inclusion: always` steering file + a one-line
 //   pointer to the active change. Everything else stays dynamic.
-// Journals what was injected so /sdlc:observe can price residency honestly.
+// Journals what was injected so /sdlc:observe can price residency honestly. When a newer
+// framework version is known, one notice line leads the output, outside the budget.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11,8 +12,9 @@ import { resolveRoots, readStdinJson, activeChange, appendJournal } from './_sha
 import { parseFrontmatter } from './lib/frontmatter.mjs';
 import { CAPS } from './lib/caps.mjs';
 import { pickSessionId } from './lib/active.mjs';
+import { updateNotice } from './_update-notice.mjs';
 
-const { sdlcRoot } = resolveRoots(import.meta.url);
+const { sdlcRoot, hooksDir } = resolveRoots(import.meta.url);
 
 async function main() {
   const input = await readStdinJson();
@@ -42,16 +44,18 @@ async function main() {
   const active = activeChange(sdlcRoot, sessionId);
   if (active) out.push(`Active change: sdlc/changes/${active}/change.md — run /sdlc:next for status.`);
 
-  if (!out.length) return;
+  const notice = updateNotice({ sdlcRoot, hooksDir });
+  if (!out.length && !notice) return;
 
-  let lines = out.join('\n\n').split('\n');
+  let lines = out.length ? out.join('\n\n').split('\n') : [];
   if (lines.length > CAPS.alwaysBudget) {
     lines = lines.slice(0, CAPS.alwaysBudget);
     lines.push(`[sdlc] static context truncated at ${CAPS.alwaysBudget} lines — run /sdlc:steer to distill (validate also flags this).`);
   }
-  console.log(lines.join('\n'));
+  console.log((notice ? [notice, ...lines] : lines).join('\n'));
 
-  appendJournal(sdlcRoot, active, { event: 'inject', files: injected, lines: lines.length });
+  // `lines` stays the budgeted count; the notice is recorded on its own, outside the budget.
+  appendJournal(sdlcRoot, active, { event: 'inject', files: injected, lines: lines.length, notice: Boolean(notice) });
 }
 
 main().catch(() => process.exit(0)); // fail open

package/payload/templates/config.yaml

@@ -4,5 +4,9 @@ tools: []            # filled by `warnyin-sdlc init`
 # Optional price table for cost reporting (USD per 1M tokens).
 # prices:
 #   claude-sonnet-5: { input: 3, output: 15, cacheRead: 0.3 }
+# Once a day a SessionStart hook asks the npm registry whether a newer @warnyin/sdlc exists
+# and, if so, tells the agent to mention `npx @warnyin/sdlc update`. It never updates by
+# itself. Uncomment to switch it off (CI or NO_UPDATE_NOTIFIER in the env also do).
+# updateCheck: false
 # Optional per-artifact cap overrides (see lib/caps.mjs for defaults).
 # caps: {}