@starci/hfs 4.7.34 → 4.7.36

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "22aaaddc27f0ed4d795adfbd63deba5f0071f15dcab2a8456f852a20798b622b",
+  "hash": "3ac967b6f4bb2136cbc7b29a8da5d28994140c84c3543ef0748a379e4667c443",
   "global": [
     {
       "name": "json",
@@ -634,7 +634,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "check": {
-          "summary": "judge the app tree, managed output, contracts, formatting and architecture",
+          "summary": "run the app ESLint canons and judge the tree, managed output, contracts, formatting and architecture",
           "owner": "@starci/hfs",
           "flags": [
             {
@@ -661,7 +661,7 @@ export const CATALOG = {
           "exit": {
             "0": "clean",
             "1": "findings",
-            "2": "refusal or bad usage"
+            "2": "a tool could not run, refusal or bad usage"
           },
           "json": "flag",
           "examples": [
@@ -789,6 +789,58 @@ export const CATALOG = {
           ],
           "runtimeSide": "host"
         },
+        "codemod": {
+          "summary": "migrate front-end button variants to declared intent and report cases requiring a human decision",
+          "owner": "@starci/hfs",
+          "positional": [
+            {
+              "name": "migration",
+              "enum": [
+                "button-intent"
+              ],
+              "required": true,
+              "variadic": false
+            }
+          ],
+          "flags": [
+            {
+              "name": "write",
+              "type": "boolean",
+              "summary": "apply safe source edits; otherwise preview without changing source"
+            },
+            {
+              "name": "format",
+              "type": "enum",
+              "enum": [
+                "json",
+                "markdown"
+              ],
+              "default": "markdown",
+              "summary": "migration report format"
+            },
+            {
+              "name": "report",
+              "type": "string",
+              "summary": "also save the complete report to a .json or .md file"
+            }
+          ],
+          "exit": {
+            "0": "migration has no unresolved cases",
+            "1": "unresolved cases require a human decision",
+            "2": "refusal or bad usage"
+          },
+          "json": "flag",
+          "examples": [
+            "starci app codemod button-intent",
+            "starci app codemod button-intent --write --format json --report button-intent.json"
+          ],
+          "editions": [
+            "full",
+            "lite"
+          ],
+          "impl": null,
+          "runtimeSide": "host"
+        },
         "coverage": {
           "summary": "merge the sharded unit coverage into one lcov report, or prove that report at 100 per file",
           "owner": "@starci/hfs",
@@ -3124,7 +3176,7 @@ export const CATALOG = {
           "json": "always",
           "examples": [
             "starci gate unit --root <app> --out unit-run.json",
-            "starci gate unit --root <app> --tests orders --subjects 'be/src/modules/orders/' --out unit-run.json"
+            "starci gate unit --root <app> --tests orders --subjects '<subject-path>' --out unit-run.json"
           ],
           "editions": [
             "full"
@@ -3269,7 +3321,7 @@ export const CATALOG = {
             "full"
           ],
           "impl": {
-            "module": "scripts/machine/git-commit.mjs",
+            "module": "scripts/guards/git-commit.mjs",
             "export": "gitCommit"
           },
           "effect": "local-write",
@@ -8617,13 +8669,14 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "the candidate CI of the release sha was green, then main plus its tag were pushed atomically, or --plan found nothing missing",
-            "1": "refused (RELEASE_CANDIDATE_CI_RED, RELEASE_CANDIDATE_CI_TIMEOUT, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, suite red, main moved, secret scan) and nothing was pushed",
+            "1": "refused (RELEASE_CANDIDATE_CI_RED, RELEASE_CANDIDATE_CI_TIMEOUT, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, RELEASE_VERSION_NOT_NEXT, suite red, main moved, secret scan) and nothing was pushed",
             "2": "bad usage"
           },
           "json": "flag",
           "examples": [
             "starci release cut",
             "starci release cut --plan --tag v1.0.0-alpha.9",
+            "starci release cut --tag v1.0.0-alpha.31.1",
             "starci release cut --tag v1.0.0-alpha.9 --rows \"npm run test:e2e,linux-parity\"",
             "starci release cut --repo <path> --tag v1.0.0-alpha.9 --json"
           ],
@@ -8634,6 +8687,9 @@ export const CATALOG = {
             "script": "scripts/supervisor/release-cut-cli.mjs"
           },
           "conventions": [
+            "Naming (owner ruling release-waves): the next release is alpha.N.M+1 of the highest v* tag (a wave or a fix) or the next line alpha.N+1,",
+            "derived from the v* tags, never guessed (RELEASE_VERSION_NOT_NEXT); without --tag the refusal names both.",
+            "The legacy -fix form is read and never cut.",
             "OWNER RULING candidate-ci (2026-10-18): never again have main receive a release whose CI is red, with the owner confirming afterwards.",
             "Before the suite, including --plan, the workflows the candidate CI waits for (release-cut.yaml candidate.workflows) must be readable,",
             "else RELEASE_CI_UNKNOWN. The latest run on main is no longer read: a red main needs no owner override before the next release.",
@@ -8884,6 +8940,7 @@ export const CATALOG = {
             "runtime-package refuses changed inputs or registry state after its cold proof and never performs rebind or example writes",
             "runtime-package plans the upload channel and release-declared npm dist-tags, repairs stale tags without republishing, and reads every target back",
             "runtime-package refuses an older release on its line and preserves tags pointing to newer releases on other lines",
+            "every alpha.N and wave alpha.N.M share the one alpha line, so a wave never moves a dist-tag behind a later wave or line",
             "publication never commits, pushes or creates Git tags; release cut owns those effects"
           ],
           "runtimeSide": "tree"
@@ -14289,6 +14346,44 @@ export const CATALOG = {
           },
           "runtimeSide": "host"
         },
+        "export-repaints": {
+          "summary": "export strict Grammar vendor findings as CSS repair assignments",
+          "owner": "runtime",
+          "flags": [
+            {
+              "name": "out-dir",
+              "type": "string",
+              "required": true,
+              "summary": "directory for the repaint exports"
+            },
+            {
+              "name": "root",
+              "type": "string",
+              "summary": "runtime root whose Grammar sources and vendor reference are judged"
+            },
+            {
+              "name": "check",
+              "type": "boolean",
+              "summary": "report export drift without writing"
+            }
+          ],
+          "exit": {
+            "0": "exports written or verified",
+            "1": "export drift or unreadable judge inputs",
+            "2": "bad usage"
+          },
+          "json": "none",
+          "examples": [
+            "starci work export-repaints --out-dir <directory>"
+          ],
+          "editions": [
+            "full"
+          ],
+          "impl": {
+            "script": "scripts/work/ui/export-repaints.mjs"
+          },
+          "runtimeSide": "host"
+        },
         "grammar-geometry": {
           "summary": "emit grammar geometry guidance or check captured geometry",
           "owner": "runtime",
@@ -14345,7 +14440,22 @@ export const CATALOG = {
             {
               "name": "write",
               "type": "boolean",
-              "summary": "rewrite the grammar DNA from the package; without it only compares"
+              "summary": "rewrite selected generated output; mutually exclusive with --check"
+            },
+            {
+              "name": "check",
+              "type": "boolean",
+              "summary": "compare selected generated output without writing (the default); mutually exclusive with --write"
+            },
+            {
+              "name": "intent-only",
+              "type": "boolean",
+              "summary": "scope generated output to DNA intent mapping blocks; may combine with --catalog-only"
+            },
+            {
+              "name": "catalog-only",
+              "type": "boolean",
+              "summary": "scope generated output to the Button and IconButton intent props catalog; may combine with --intent-only"
             }
           ],
           "exit": {
@@ -14919,7 +15029,7 @@ export const CATALOG = {
             {
               "name": "family",
               "type": "string",
-              "summary": "grammar family to use instead of the detected one (a registered grammar family id)"
+              "summary": "explicit registered Grammar family; otherwise read sides.fe.grammar from the app declaration"
             },
             {
               "name": "elements",
@@ -14941,7 +15051,7 @@ export const CATALOG = {
           "exit": {
             "0": "brief printed or the score is clean",
             "1": "a scoring finding",
-            "2": "bad usage"
+            "2": "bad usage or unavailable presentation source"
           },
           "json": "flag",
           "examples": [

package/runtime/scripts/gates/canon-pins.mjs

@@ -3,14 +3,117 @@
 // The gates read the pins here; scripts/checks/check-canon-pins.mjs is the self-check that judges them.
 import fs from 'node:fs';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
+import { grammarLintFor } from '../lib/grammar-lint.mjs';
+import { locateDeclaration } from '../hfs/slots.mjs';
+import { pathKey, posixPath } from '../lib/path-key.mjs';
+import { canonContentDigest, installedFiles } from './canon-digest.mjs';
 
 export const PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const SCHEMA_FILE = 'modules/schemas/canon-pins.schema.yaml';
 export const PROFILES_FILE = 'modules/models/code-patterns.yaml';
+/** A missing, mismatched or unjudged installed canon remains a failing gate. */
+export const CANON_INSTALL_CODES = Object.freeze({ missing: 'CANON_INSTALL_MISSING', mismatch: 'CANON_INSTALL_MISMATCH', unjudged: 'CANON_INSTALL_UNJUDGED' });
 
 /** The parsed canon pins of the runtime at `root`. */
 export function loadPins(root = skillRoot) {
   return parseYaml(fs.readFileSync(path.join(root, PINS_FILE), 'utf8'));
 }
+
+/** Every independently published canon binding of a profile, including each declared Grammar family. */
+export function profileCanonBindings(profile) {
+  return [
+    { binding: 'canon', canon: profile?.canon },
+    ...Object.entries(profile?.familyCanons ?? {}).map(([family, canon]) => ({ binding: `familyCanons.${family}`, family, canon })),
+  ];
+}
+
+/** The zero-based source lines that author actual profile canon versions, including named family bindings. */
+export function canonBindingVersionLines(text) {
+  const profiles = parseYaml(text)?.profiles ?? {};
+  const bindings = new Map(Object.entries(profiles).flatMap(([profile, value]) => profileCanonBindings(value)
+    .filter(row => typeof row.canon?.package === 'string' && typeof row.canon?.version === 'string')
+    .map(row => [JSON.stringify(['profiles', profile, ...row.binding.split('.')]), row.canon])));
+  const leaves = new Map(), stack = [];
+  text.split('\n').forEach((line, index) => {
+    const separator = line.indexOf(':'), field = line.slice(0, separator), key = field.trim();
+    if (separator < 0 || !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) return;
+    const indent = field.length - field.trimStart().length, value = line.slice(separator + 1).trimStart();
+    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
+    const keys = [...stack.map(entry => entry.key), key];
+    let binding = bindings.get(JSON.stringify(keys));
+    if (key === 'version') binding = bindings.get(JSON.stringify(keys.slice(0, -1)));
+    if (binding && (key === 'version' || /^\{.*\bversion\s*:/.test(value))) leaves.set(index, { package: binding.package, version: binding.version });
+    stack.push({ key, indent });
+  });
+  return leaves;
+}
+
+/** The universal binding and the explicitly selected family's binding; no absent selection implies a family. */
+export function selectedProfileCanonBindings(profile, family) {
+  const bindings = [{ binding: 'canon', canon: profile?.canon }];
+  if (!profile?.familyCanons) return bindings;
+  const contract = grammarLintFor(family);
+  if (contract.package === null) return bindings;
+  const canon = profile.familyCanons[contract.family];
+  if (!canon || canon.package !== contract.package) {
+    throw new Error(`Grammar family ${contract.family} has no matching code-pattern canon binding for ${contract.package}`);
+  }
+  return [...bindings, { binding: `familyCanons.${contract.family}`, family: contract.family, canon }];
+}
+
+/** The package root resolved from a side's npm install, without admitting an install above the app boundary. */
+function installedPackageRoot(directory, name, bound) {
+  const top = pathKey(bound);
+  const searched = (createRequire(path.join(directory, 'package.json')).resolve.paths(name) ?? []).filter(modules => pathKey(modules).startsWith(`${top}/`));
+  for (const modules of searched) {
+    const candidate = path.join(modules, ...name.split('/'));
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);
+  }
+  return null;
+}
+
+/** Inspect one selected binding's actual installed bytes; errors remain unavailable and mismatches remain findings. */
+function inspectBinding(root, bound, pins, profile, row, out) {
+  const { canon, family } = row, side = pins[canon?.package]?.side;
+  const label = row.binding === 'canon' ? profile : `${profile}.${row.binding}`;
+  if (!canon?.package || typeof side !== 'string') { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: canon.package ${canon?.package} has no pinned side`); return; }
+  const installed = installedPackageRoot(path.join(root, side), canon.package, bound);
+  if (!installed) { out.errors.push(`${CANON_INSTALL_CODES.missing} profile ${label}: ${canon.package} does not resolve from ${side}/ of the app; install the pinned ${canon.version}`); return; }
+  const where = posixPath(path.relative(root, installed));
+  let manifest, version, digest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8'));
+    version = manifest.version ?? null;
+    digest = canonContentDigest(installed, canon.contentDigest, installedFiles(installed));
+  } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${label}: ${error.code ?? 'ERROR'} ${error.message}`); return; }
+  out.checked.push({ profile: label, ...(family ? { family } : {}), package: canon.package, side, path: where, version, digest: digest.value, files: digest.files });
+  if (version !== canon.version || digest.value !== canon.contentDigest.value || digest.files !== canon.contentDigest.files) {
+    out.findings.push({ engine: 'canon', rule: 'installed-canon-mismatch', path: where, line: null,
+      message: `${canon.package} installed for ${side}/ is ${version} with ${digest.files} files digesting ${digest.value}; profile ${label} binds ${canon.version} with ${canon.contentDigest.files} files digesting ${canon.contentDigest.value} (${CANON_INSTALL_CODES.mismatch}: reinstall the pinned version from the registry)` });
+  }
+  return Object.keys(manifest.dependencies ?? {});
+}
+
+/** Judge the universal and explicitly selected family installs against their independent version/content bindings. */
+export function inspectInstalledCanons(root, { pins, profiles, bound = root }) {
+  const out = { checked: [], findings: [], errors: [] };
+  for (const [profile, value] of Object.entries(profiles)) {
+    let bindings;
+    try {
+      const declaration = value?.familyCanons ? JSON.parse(fs.readFileSync(locateDeclaration(root).file, 'utf8')) : null;
+      bindings = selectedProfileCanonBindings(value, declaration?.sides?.fe?.grammar);
+    } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} profile ${profile}: ${error.message}`); continue; }
+    const available = profileCanonBindings(value), checked = new Set();
+    for (const row of bindings) {
+      if (checked.has(row.canon?.package)) continue;
+      checked.add(row.canon?.package);
+      const dependencies = inspectBinding(root, bound, pins, profile, row, out) ?? [];
+      // A family adapter's digest does not cover its independently published implementation dependency.
+      bindings.push(...available.filter(entry => dependencies.includes(entry.canon?.package) && !checked.has(entry.canon.package)));
+    }
+  }
+  return out;
+}

package/runtime/scripts/gates/gate.mjs

@@ -53,8 +53,7 @@ import { APP_SCOPE, HFS_DECLARATION_FILE, locateDeclaration } from '../hfs/slots
 import { runNode } from '../api/node/run-node.mjs';
 import { sha256 } from '../../engine/digest.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { canonContentDigest, installedFiles } from './canon-digest.mjs';
-import { PROFILES_FILE, loadPins } from './canon-pins.mjs';
+import { CANON_INSTALL_CODES, PROFILES_FILE, inspectInstalledCanons, loadPins } from './canon-pins.mjs';
 import { gateGit as git, gateGitText as gitText, resolveGateBase, gateDelta, gateInputSnapshot } from './gate-input.mjs';
 export { resolveGateBase, gateInputSnapshot } from './gate-input.mjs';
 import { jestRunError, reduceJest } from './test-world-run.mjs';
@@ -438,21 +437,6 @@ export function mergeGuard(root, { base, head = 'HEAD', mainTip = mainTipOf(root
 }
 
 /* ----------------------------------------------------------------------------------------- installed canon */
-const INSTALL = Object.freeze({ missing: 'CANON_INSTALL_MISSING', mismatch: 'CANON_INSTALL_MISMATCH', unjudged: 'CANON_INSTALL_UNJUDGED' });
-
-/**
- * The installed root of package `name` as node resolves it from `directory` (its node_modules walk), never above `bound` (the
- * app root, appRootOf): a canon in an enclosing repository's node_modules is not this app's install. Null when none.
- */
-function installedPackageRoot(directory, name, bound) {
-  const top = pathKey(bound);
-  const searched = (createRequire(path.join(directory, 'package.json')).resolve.paths(name) ?? []).filter((modules) => pathKey(modules).startsWith(`${top}/`));
-  for (const modules of searched) {
-    const candidate = path.join(modules, ...name.split('/'));
-    if (fs.existsSync(path.join(candidate, 'package.json'))) return fs.realpathSync(candidate);
-  }
-  return null;
-}
 /**
  * Every profile's canon as installed under the app at `root`, judged against its binding in `runtime`'s code-patterns.yaml:
  * the package resolved from the pin's side directory must have the bound version and content digest.
@@ -464,25 +448,8 @@ export function installedCanonFindings(root, { runtime = runtimeRoot } = {}) {
   try {
     pins = loadPins(runtime).pins ?? {};
     profiles = parseYaml(fs.readFileSync(path.join(runtime, PROFILES_FILE), 'utf8'))?.profiles ?? {};
-  } catch (error) { out.errors.push(`${INSTALL.unjudged} the canon bindings are unreadable: ${error.message}`); return out; }
-  for (const [profile, value] of Object.entries(profiles)) {
-    const canon = value?.canon, side = pins[canon?.package]?.side;
-    if (!canon?.package || typeof side !== 'string') { out.errors.push(`${INSTALL.unjudged} profile ${profile}: canon.package ${canon?.package} has no pinned side`); continue; }
-    const installed = installedPackageRoot(path.join(root, side), canon.package, appRootOf(root, path.join(side, 'package.json')));
-    if (!installed) { out.errors.push(`${INSTALL.missing} profile ${profile}: ${canon.package} does not resolve from ${side}/ of the app; install the pinned ${canon.version}`); continue; }
-    const where = posixPath(path.relative(root, installed));
-    let version, digest;
-    try {
-      version = JSON.parse(fs.readFileSync(path.join(installed, 'package.json'), 'utf8')).version ?? null;
-      digest = canonContentDigest(installed, canon.contentDigest, installedFiles(installed));
-    } catch (error) { out.errors.push(`${INSTALL.unjudged} profile ${profile}: ${error.code ?? 'ERROR'} ${error.message}`); continue; }
-    out.checked.push({ profile, package: canon.package, side, path: where, version, digest: digest.value, files: digest.files });
-    if (version !== canon.version || digest.value !== canon.contentDigest.value || digest.files !== canon.contentDigest.files) {
-      out.findings.push({ engine: 'canon', rule: 'installed-canon-mismatch', path: where, line: null,
-        message: `${canon.package} installed for ${side}/ is ${version} with ${digest.files} files digesting ${digest.value}; profile ${profile} binds ${canon.version} with ${canon.contentDigest.files} files digesting ${canon.contentDigest.value} (${INSTALL.mismatch}: reinstall the pinned version from the registry)` });
-    }
-  }
-  return out;
+  } catch (error) { out.errors.push(`${CANON_INSTALL_CODES.unjudged} the canon bindings are unreadable: ${error.message}`); return out; }
+  return inspectInstalledCanons(root, { pins, profiles, bound: appRootOf(root, 'package.json') });
 }
 
 /* ----------------------------------------------------------------------------------------------- gate */

package/runtime/scripts/gates/output.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {redactBytes} from '../lib/redact.mjs';
+
+/** Print a gate summary, retain an optional scratch copy, and return its measured exit code. */
+export function emitGateSummary(summary, out = null, write = text => process.stdout.write(text)) {
+  const text = `${JSON.stringify(summary, null, 2)}\n`;
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, text);
+  }
+  write(text);
+  return summary.exit;
+}
+
+/**
+ * Write a check result to scratch, stdout, or the external content-addressed store. A blob is redacted first when its
+ * media type is text (scripts/lib/redact.mjs); the printed {sha, redaction} is what a check_runs row cites.
+ */
+export async function emitCheckOutput(value, {out = null, blob = false, mediaType = 'application/json',
+  write = text => process.stdout.write(text), put = null} = {}) {
+  if (out && blob) throw new Error('--out and --blob are mutually exclusive');
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value));
+  if (out) {
+    const file = path.resolve(out);
+    fs.mkdirSync(path.dirname(file), {recursive: true});
+    fs.writeFileSync(file, bytes);
+    return {out: file};
+  }
+  if (blob) {
+    const putBlob = put ?? (await import('../../engine/db/blob.mjs')).putBlob;
+    const clean = redactBytes(bytes, mediaType);
+    const {sha} = await putBlob(clean.bytes, {mediaType});
+    write(`${JSON.stringify({sha, redaction: clean.redaction})}\n`);
+    return {sha, redaction: clean.redaction};
+  }
+  write(bytes.toString());
+  return {};
+}

package/runtime/scripts/gates/test-world-run.mjs

@@ -26,6 +26,7 @@ import { valueFlags } from '../lib/cli-arg.mjs';
 import { isMain } from '../lib/is-main.mjs'; import { walkFiles } from '../lib/walk.mjs';
 import { opGateRules } from '../lib/op-gate.mjs';
 import { makeTempDir } from '../api/fs/make-temp-dir.mjs';
+import { emitGateSummary } from './output.mjs';
 
 export const TEST_WORLD_RUN_SCHEMA = 'starci/test-world-run@1';
 const WORLD_PROJECTS = Object.freeze({
@@ -243,10 +244,7 @@ if (isMain(import.meta.url)) {
   try {
     const opts = parseTestWorldArgs(process.argv.slice(2));
     const summary = buildTestWorldRun({ root: opts.root ?? process.cwd(), project: opts.project, tests: opts.tests });
-    const text = `${JSON.stringify(summary, null, 2)}\n`;
-    if (opts.out) { fs.mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true }); fs.writeFileSync(path.resolve(opts.out), text); }
-    process.stdout.write(text);
-    process.exitCode = summary.exit;
+    process.exitCode = emitGateSummary(summary, opts.out);
   } catch (error) {
     process.stderr.write(`test-world-run: ${error.message}\n`);
     process.exitCode = 2;

package/runtime/scripts/guards/release-definition.mjs

@@ -2,6 +2,8 @@
 // pre-push hook (scripts/guards/release-push-gate.mjs) and the release cut (scripts/supervisor/release-cut.mjs). The remote
 // main of the runtime moves exactly when a release is cut, so a push of main or of a v* tag is judged against this list:
 //   RELEASE_VERSION_UNCHANGED   package.json `version` at the pushed commit differs from the version at the remote main's head
+//   RELEASE_VERSION_NOT_NEXT    that version is the next release after the highest v* tag (scripts/lib/release-version.mjs, owner ruling release-waves):
+//                               the next wave alpha.N.M+1 of its line or the next line alpha.N+1, never the legacy -fix form
 //   RELEASE_TAG_VERSION         the release tag is v<version> of the pushed commit
 //   RELEASE_CHANGELOG_SECTION   CHANGELOG.md holds `## [<version>] - <date>` (a dated heading) with no unfinished marker (R222)
 //   RELEASE_TAG_MISSING         an ANNOTATED tag v<version> points at the pushed commit
@@ -17,6 +19,7 @@ import { tag as gitTag } from '../api/git/tag.mjs';
 import { mergeBaseQuery } from '../api/git/merge-base-query.mjs';
 import { pathKey, realPath } from '../lib/path-key.mjs';
 import { changelogSection, releaseNotesFindings } from '../hfs/runtime-rules/release-notes.mjs';
+import { nextReleases, releaseVersionRefusal, taggedVersions } from '../lib/release-version.mjs';
 import { readL4Record } from './release-record.mjs';
 import { suiteModeOf } from './release-suite-mode.mjs';
 
@@ -122,14 +125,27 @@ function releaseAncestor(repo, before, after) {
   return null;
 }
 
-function versionFindings({ cwd, commit, remoteCommit, version }) {
+/** The next releases named from the released versions, for a fix text: "v<wave> or v<line>". */
+const nextNamed = (released) => {
+  const next = nextReleases(released);
+  return next ? `v${next.wave} or v${next.line}` : 'v<new version>';
+};
+
+function versionFindings({ cwd, remoteCommit, version, released }) {
   if (!remoteCommit) return [];
   const remoteVersion = versionAt(cwd, remoteCommit);
   if (remoteVersion === null) return [finding('RELEASE_REMOTE_HEAD_UNKNOWN', `the remote main head ${remoteCommit.slice(0, 9)} is not in this repository, so its version cannot be compared`, 'git fetch origin main')];
-  if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `bump package.json version, move the CHANGELOG section to the new version, commit, then ${CUT_COMMAND('v<new version>')}`)];
+  if (remoteVersion === version) return [finding('RELEASE_VERSION_UNCHANGED', `package.json version ${version} is the version the remote main already carries`, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released))}`)];
   return [];
 }
 
+/** The version must be the next release after the highest v* tag other than its own: a wave alpha.N.M is counted, never guessed. */
+function nextReleaseFindings({ version, released }) {
+  if (released === null) return [finding('RELEASE_VERSION_NOT_NEXT', 'the v* tags are unreadable, so the next release cannot be derived', 'git fetch --tags')];
+  const refusal = releaseVersionRefusal(version, released);
+  return refusal ? [finding('RELEASE_VERSION_NOT_NEXT', refusal, `set package.json version to the next release, move the CHANGELOG section to it, commit, then ${CUT_COMMAND(nextNamed(released.filter((entry) => entry !== version)))}`)] : [];
+}
+
 function changelogFindings({ cwd, commit, version, tag }) {
   const changelog = gitText(show, [`${commit}:CHANGELOG.md`], cwd);
   if (changelog === null) return [finding('RELEASE_CHANGELOG_SECTION', 'CHANGELOG.md is not readable at the pushed commit', 'restore CHANGELOG.md')];
@@ -176,8 +192,11 @@ export function releaseFindings({ cwd, commit, remoteCommit = null, tag = null,
   const expected = `v${version}`;
   const named = tag ?? expected;
   if (named !== expected) return [finding('RELEASE_TAG_VERSION', `the tag ${named} is not v${version}, the version of ${commit.slice(0, 9)}`, `tag v${version}, or set package.json version to ${named.replace(/^v/, '')}`)];
+  const listed = gitText(gitTag, ['--list', 'v*'], cwd);
+  const released = listed === null ? null : taggedVersions(listed);
   return [
-    ...versionFindings({ cwd, commit, remoteCommit, version }),
+    ...versionFindings({ cwd, remoteCommit, version, released: released ?? [] }),
+    ...nextReleaseFindings({ version, released }),
     ...changelogFindings({ cwd, commit, version, tag: named }),
     ...(needTag ? tagFindings({ cwd, commit, tag: named }) : []),
     ...(needReceipt ? receiptFindings({ cwd, commit, tag: named }) : []),

package/runtime/scripts/hfs/architecture/config.mjs

@@ -5,6 +5,7 @@ import { readJsonFile as readJson } from '../../lib/json.mjs';
 import { isInside } from '../../lib/walk.mjs';
 import { openHfs } from '../slots.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { grammarContractFor } from '../../lib/grammar-lint.mjs';
 
 
 /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -270,19 +271,18 @@ function derivedOwners(root, resolver) {
 
 const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
 
-const GRAMMAR_PACKAGE = '@starci/grammar';
-
 /**
- * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
- * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
+ * The selected family's component contract with derived consumers: every app's globals.css is a style
+ * source, every app and every workspace package that depends on its package is a consumer. null when no app has
  * a globals.css to judge (the contract is then reported unavailable, never passed).
  */
-function derivedGrammar(root, packageRoot, workspaces, apps = []) {
+function derivedGrammar(root, packageRoot, workspaces, apps, family) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
+  const contract = grammarContractFor(family);
   // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
   // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
-  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
+  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, contract.package)));
   const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
   const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
@@ -292,7 +292,7 @@ function derivedGrammar(root, packageRoot, workspaces, apps = []) {
     if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
-  return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react', '@xyflow/react'] };
+  return { ...contract, styleSources, consumerManifests };
 }
 
 /**
@@ -328,7 +328,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
     hooks: inferred.hooks,
     modules: inferred.modules,
     transport: inferred.transport,
-    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
+    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps, opened.repo.grammar) : null,
   };
   if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
   return {

package/runtime/scripts/hfs/check.mjs

@@ -341,7 +341,7 @@ function mergeBaseOf(repoRoot, base) {
 }
 
 /** Tracked paths that differ from the merge-base (commits, staged and unstaged edits; deletions are not paths to judge). */
-function changedSince(repoRoot, base) {
+export function changedSince(repoRoot, base) {
   const sha = mergeBaseOf(repoRoot, base);
   if (!sha) {
     throw new Error(base

package/runtime/scripts/hfs/db-restamp-verb.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { parseYaml } from '../../engine/yaml.mjs';
 import { invocationDir } from '../lib/roots.mjs';
 import { migrationStamp } from './rules/database-migrations.mjs';
-import { isActiveMigration, MIGRATIONS_DIR } from './rules/database-constants.mjs';
+import { MIGRATIONS_DIR } from './rules/database-constants.mjs';
 import { DbVerbError, dbOptions, dbAppRoot, dbSqlFiles, runDbSupabase, repairArgs, dbFailure } from './db-baseline-verb.mjs';
 
 /** The map value of one old version: a new version, or { file, to, applied } for the colliding-versions case. */
@@ -55,7 +55,7 @@ function restampPlan(root, mapFile, { local = false, ports = {} } = {}) {
   catch { throw new DbVerbError('restamp map must be readable YAML with unique version keys'); }
   const mapping = document?.versions ?? document;
   if (!mapping || typeof mapping !== 'object' || Array.isArray(mapping) || !Object.keys(mapping).length) throw new DbVerbError('restamp map must contain old-to-new version pairs');
-  const active = dbSqlFiles(root).filter((entry) => isActiveMigration(entry.file));
+  const active = dbSqlFiles(root);
   const occupied = new Set(active.map((entry) => entry.stamp));
   const targets = new Set();
   const steps = Object.entries(mapping).map(([old, raw]) => {

package/runtime/scripts/hfs/declaration-shape.mjs

@@ -73,11 +73,17 @@ function extraPackageProblems(side, entries) {
   return [];
 }
 
+function grammarProblems(side, grammar) {
+  if (grammar === undefined) return [];
+  if (side !== 'fe') return ['grammar belongs to the fe side'];
+  return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
+}
+
 function declarationSideProblems(side, value, names) {
   const bad = [];
   const at = `sides.${side}`;
   if (!isPlainObject(value)) return [`${at} must be an object`];
-  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
+  for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
   bad.push(...appShapeProblems(value.apps, at, side, names));
   if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
   if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
@@ -85,7 +91,7 @@ function declarationSideProblems(side, value, names) {
   bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
   if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
   if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
-  bad.push(...extraPackageProblems(side, value.extraPackages));
+  bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
   return bad;
 }