@starci/hfs 4.7.35 → 4.7.37

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 4.7.37 - 2026-10-26
+- Fixed: the scaffold SiteShell declares viewport=flow so Grammar lint reads it as site chrome, the hygiene sync follows the scaffold end-to-end fixes, and the scaffold json-logger spec expects the logger field order.
+
+## 4.7.36 - 2026-10-26
+- Changed: the bundled canon pins select @starci/eslint-canon-be 3.4.45, @starci/eslint-canon-fe 9.1.0, the Grammar lint families 0.12.4 and @starci/grammar 0.12.4.
+- Added: the five R319 button-intent finding codes are catalogued and proven, and the `app codemod button-intent` migration is bundled.
+- Changed: the Grammar vendor-parity proof is strict. It reads the DNA vendor, parity and arrangement declarations, judges undeclared wraps and stale overrides, and exports repaint findings with `starci work export-repaints`; `wrappers.yaml` carries the owner-ruled overrides and one pin.
+- Changed: releases follow the alpha.N.M counter (owner ruling `release-waves`): the next tag is derived from the highest released one.
+
 ## 4.7.35 - 2026-10-26
 - Changed: the bundled canon pins select @starci/stylelint-canon 2.0.12, @starci/eslint-canon-be 3.4.44, @starci/eslint-canon-fe 9.0.0, the Grammar lint families 0.12.3 and @starci/grammar 0.12.3.
 - Added: `app lint` composes the selected Grammar family lint with the universal front-end canon and refuses canon-fe 9 without it; the Grammar vendor-parity proof reads the generated HeroUI reference; the UI proof checks component ownership and surface layers.
@@ -7,6 +16,7 @@
 - Changed: the runtime centralizes its parsing and gate summaries.
 
 ## 4.7.34 - 2026-10-26
+- Added: `starci app codemod button-intent` previews legacy Grammar button migrations, applies safe edits with `--write`, and reports ambiguous consequences, competing commits and repeated item commits in JSON or Markdown.
 - Fixed: `starci app db restamp` considers only active migrations when validating names and choosing unoccupied versions. Legacy archive names no longer block preview or apply, and archived files stay untouched.
 - Changed: the loosening check reads the tree as it stands and never its history. The bundled `scripts/lib/loosening-state.mjs` (with `js-lex.mjs` and `loosening-config.mjs`) replaces the diff detector; `HFS_BYPASS_MARKER` (R303) reads it: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell, a package.json is judged by its scripts, and the same words quoted as data are no bypass. It also refuses a coverage target or threshold below the canon, a relaxing switch, a disabled ESLint rule, a tsconfig strictness option turned off and an exception file that `knowledge/hfs/design-truths.yaml` does not list. `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern` and a `--max-warnings` budget are bypasses in a script, a hook or a workflow.
 - Added: `starci app emit` carries class-validator `MaxLength`, `ArrayMaxSize`, `Min` and `Max` of GraphQL input types and REST operation DTOs into the contract (a GraphQL `@inputBounds` directive and an OpenAPI constraint), and the `@starci/hfs/form-bounds` codegen plugin turns them into typed `INPUT_BOUNDS` and `inputBoundsIssues` for the form canon. The app codegen template refuses legacy or unsupported bounds metadata.

package/codemod/button-intent.mjs

@@ -0,0 +1,356 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
+import { sourceLocation } from '../runtime/scripts/lib/ts-ast.mjs';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GRAMMAR = /^@starci\/grammar(?:\/|$)/;
+const VARIANTS = Object.freeze({ primary: 'commit', tertiary: 'dismiss', danger: 'destructive', 'danger-soft': 'destructive', outline: 'neutral', ghost: 'neutral' });
+const WEAK = new Set(['outline', 'ghost', 'secondary']);
+const GENERATED = new Set(['node_modules', '.next', '.turbo', 'dist', 'coverage', '.git']);
+
+function attributes(ts, opening) {
+  return new Map(opening.attributes.properties.filter(ts.isJsxAttribute).map(prop => [prop.name.getText(), prop]));
+}
+
+function literal(ts, attribute) {
+  const value = attribute?.initializer;
+  if (value && ts.isStringLiteralLike(value)) return value.text;
+  return value && ts.isJsxExpression(value) && value.expression && ts.isStringLiteralLike(value.expression) ? value.expression.text : null;
+}
+
+function buttonImports(ts, source) {
+  const names = new Set();
+  const namespaces = new Set();
+  for (const node of source.statements) {
+    if (!ts.isImportDeclaration(node) || !GRAMMAR.test(node.moduleSpecifier.text)) continue;
+    const bindings = node.importClause?.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const binding of bindings.elements) {
+        if (['Button', 'IconButton'].includes(binding.propertyName?.text ?? binding.name.text)) names.add(binding.name.text);
+      }
+    }
+  }
+  return { names, namespaces };
+}
+
+function isButton(ts, opening, imports) {
+  const tag = opening.tagName;
+  if (ts.isIdentifier(tag)) return imports.names.has(tag.text);
+  return ts.isPropertyAccessExpression(tag) && ts.isIdentifier(tag.expression)
+    && imports.namespaces.has(tag.expression.text) && ['Button', 'IconButton'].includes(tag.name.text);
+}
+
+function bindingNames(ts, binding) {
+  if (ts.isIdentifier(binding)) return [binding.text];
+  if (ts.isObjectBindingPattern(binding) || ts.isArrayBindingPattern(binding)) return binding.elements.flatMap(element => ts.isBindingElement(element) ? bindingNames(ts, element.name) : []);
+  return [];
+}
+
+function shadowedBinding(ts, opening) {
+  const tag = opening.tagName;
+  const name = ts.isIdentifier(tag) ? tag.text : tag.expression.text;
+  for (let at = opening.parent; at && !ts.isSourceFile(at); at = at.parent) {
+    if (ts.isFunctionLike(at) && (at.parameters.some(parameter => bindingNames(ts, parameter.name).includes(name))
+      || (ts.isFunctionExpression(at) && at.name?.text === name))) return true;
+    if (ts.isCatchClause(at) && at.variableDeclaration && bindingNames(ts, at.variableDeclaration.name).includes(name)) return true;
+    const statements = ts.isBlock(at) ? at.statements : [];
+    for (const statement of statements) {
+      if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name?.text === name) return true;
+      if (ts.isVariableStatement(statement) && statement.declarationList.declarations.some(declaration => bindingNames(ts, declaration.name).includes(name))) return true;
+    }
+    if ((ts.isForStatement(at) || ts.isForOfStatement(at) || ts.isForInStatement(at)) && at.initializer && ts.isVariableDeclarationList(at.initializer)
+      && at.initializer.declarations.some(declaration => bindingNames(ts, declaration.name).includes(name))) return true;
+  }
+  return false;
+}
+
+function isMap(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  return ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text === 'map'
+    : ts.isElementAccessExpression(node.expression) && ts.isStringLiteralLike(node.expression.argumentExpression) && node.expression.argumentExpression.text === 'map';
+}
+
+function callbackArgument(ts, node) {
+  let expression = node;
+  while (expression.parent && ts.isParenthesizedExpression(expression.parent)) expression = expression.parent;
+  return isMap(ts, expression.parent) && expression.parent.arguments[0] === expression;
+}
+
+function inlineRenderCallback(ts, node) {
+  let expression = node;
+  while (expression.parent && ts.isParenthesizedExpression(expression.parent)) expression = expression.parent;
+  if (!expression.parent || !ts.isJsxExpression(expression.parent)) return false;
+  const container = expression.parent.parent;
+  if (ts.isJsxElement(container) || ts.isJsxFragment(container)) return true;
+  return ts.isJsxAttribute(container) && /^(?:children|render[A-Z].*|.*Renderer)$/.test(container.name.getText());
+}
+
+/** Resolve same-file callback aliases before walking buttons: ancestry alone misses rows.map(renderRow). */
+function collectionCallbacks(ts, source) {
+  const definitions = new Map();
+  const callbacks = [];
+  const collect = node => {
+    if (isMap(ts, node) && node.arguments[0]) callbacks.push(node.arguments[0]);
+    const name = (ts.isVariableDeclaration(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) && node.name;
+    if (name && ts.isIdentifier(name)) definitions.set(name.text, [...(definitions.get(name.text) ?? []), ts.isVariableDeclaration(node) ? node.initializer : node]);
+    ts.forEachChild(node, collect);
+  };
+  collect(source);
+  const owners = new Set();
+  const seen = new Set();
+  const resolve = node => {
+    if (!node || seen.has(node)) return;
+    seen.add(node);
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) owners.add(node);
+    else if (ts.isIdentifier(node)) for (const definition of definitions.get(node.text) ?? []) resolve(definition);
+    else if (ts.isParenthesizedExpression(node)) resolve(node.expression);
+    else if (ts.isPropertyAccessExpression(node)) for (const definition of definitions.get(node.name.text) ?? []) resolve(definition);
+    else if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === 'bind') resolve(node.expression.expression);
+  };
+  for (const callback of callbacks) resolve(callback);
+  return owners;
+}
+
+function renderOwner(ts, node, source) {
+  for (let at = node.parent; at; at = at.parent) {
+    if (ts.isArrowFunction(at) || ts.isFunctionExpression(at) || ts.isFunctionDeclaration(at) || ts.isMethodDeclaration(at)) {
+      // Collection and JSX render callbacks belong to their enclosing component's render, including nested SlotView children.
+      if (callbackArgument(ts, at) || inlineRenderCallback(ts, at)) continue;
+      return at;
+    }
+  }
+  return source;
+}
+
+function inMap(ts, node, owner) {
+  for (let at = node.parent; at && at !== owner; at = at.parent) {
+    if (isMap(ts, at)) return true;
+  }
+  return false;
+}
+
+function siblingGroup(ts, node, owner) {
+  for (let at = node.parent; at && at !== owner; at = at.parent) {
+    if (ts.isJsxElement(at) || ts.isJsxFragment(at)) return at;
+  }
+  return owner;
+}
+
+function stableName(ts, node) {
+  if (ts.isIdentifier(node)) return node.text;
+  if (ts.isPropertyAccessExpression(node) && stableName(ts, node.expression)) return `${stableName(ts, node.expression)}.${node.name.text}`;
+  return null;
+}
+
+function conditionFact(ts, expression, choice) {
+  if (ts.isParenthesizedExpression(expression)) return conditionFact(ts, expression.expression, choice);
+  if (ts.isPrefixUnaryExpression(expression) && expression.operator === ts.SyntaxKind.ExclamationToken) return conditionFact(ts, expression.operand, !choice);
+  if (ts.isBinaryExpression(expression)) {
+    const operator = expression.operatorToken.kind;
+    const equality = operator === ts.SyntaxKind.EqualsEqualsEqualsToken;
+    const inequality = operator === ts.SyntaxKind.ExclamationEqualsEqualsToken;
+    if (!equality && !inequality) return null;
+    const name = stableName(ts, expression.left);
+    const value = expression.right;
+    if (name && (ts.isStringLiteralLike(value) || ts.isNumericLiteral(value) || [ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(value.kind))) {
+      const canonical = ts.isStringLiteralLike(value) ? `string:${value.text}` : ts.isNumericLiteral(value) ? `number:${Number(value.text)}` : value.getText();
+      return { name, value: canonical, equal: equality === choice };
+    }
+  }
+  const name = stableName(ts, expression);
+  return name ? { name, value: 'truthy', equal: choice } : null;
+}
+
+function branchChoices(ts, node, owner) {
+  const choices = new Map();
+  const facts = [];
+  const record = (branch, expression, choice) => {
+    choices.set(branch, choice);
+    const fact = conditionFact(ts, expression, choice);
+    if (fact) facts.push(fact);
+  };
+  for (let at = node; at.parent && at.parent !== owner; at = at.parent) {
+    const parent = at.parent;
+    if (ts.isConditionalExpression(parent)) {
+      if (at === parent.whenTrue) record(parent, parent.condition, true);
+      if (at === parent.whenFalse) record(parent, parent.condition, false);
+    }
+    if (ts.isIfStatement(parent)) {
+      if (at === parent.thenStatement) record(parent, parent.expression, true);
+      if (at === parent.elseStatement) record(parent, parent.expression, false);
+    }
+    if (ts.isBinaryExpression(parent) && at === parent.right) {
+      if (parent.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) record(parent, parent.left, true);
+      if (parent.operatorToken.kind === ts.SyntaxKind.BarBarToken) record(parent, parent.left, false);
+    }
+  }
+  return { choices, facts };
+}
+
+function canCoexist(first, second) {
+  for (const [branch, choice] of first.branches) if (second.branches.has(branch) && second.branches.get(branch) !== choice) return false;
+  for (const left of first.facts) for (const right of second.facts) {
+    if (left.name !== right.name) continue;
+    if (left.value === right.value && left.equal !== right.equal) return false;
+    if (left.equal && right.equal && left.value !== right.value && left.value !== 'truthy' && right.value !== 'truthy') return false;
+  }
+  return true;
+}
+
+function destructiveSignal(text) {
+  const words = text.normalize('NFD').replace(/\p{M}/gu, '').replaceAll('\u0111', 'd').replaceAll('\u0110', 'D')
+    .replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[_-]+/g, ' ').toLowerCase();
+  return /\b(delete|remove|revoke|discard|destroy|purge|trash|terminate|clear|erase|reset|reject|decline|xoa)\b|\bthu[\s_-]*hoi\b|\b(?:cancel|huy)[\s_-]+(?:offer|booking|appointment|order|subscription|lich|don|de\s+nghi)\b/.test(words);
+}
+
+function describe(ts, source, opening, imports, callbacks) {
+  const props = attributes(ts, opening);
+  const element = ts.isJsxOpeningElement(opening) ? opening.parent : opening;
+  const owner = renderOwner(ts, element, source);
+  const variant = literal(ts, props.get('variant'));
+  const intent = literal(ts, props.get('intent'));
+  const branch = branchChoices(ts, element, owner);
+  return { opening, element, owner, props, variant, intent, branches: branch.choices, facts: branch.facts,
+    group: siblingGroup(ts, element, owner), mapped: variant === 'secondary' ? null : VARIANTS[variant],
+    repeated: callbacks.has(owner) || inMap(ts, element, owner), shadowed: shadowedBinding(ts, opening), name: opening.tagName.getText(source), imports };
+}
+
+/** Migrate imported Grammar buttons using source edits; ambiguous buttons retain their original props and gain a report finding. */
+export function transformButtonIntent({ ts, text, file = 'component.tsx' }) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, /\.jsx$/i.test(file) ? ts.ScriptKind.JSX : ts.ScriptKind.TSX);
+  const imports = buttonImports(ts, source);
+  const callbacks = collectionCallbacks(ts, source);
+  const buttons = [];
+  const visit = node => {
+    if ((ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) && isButton(ts, node, imports)) buttons.push(describe(ts, source, node, imports, callbacks));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  const findings = [];
+  const changes = [];
+  const edits = [];
+  const flag = (button, code, reason) => findings.push({ file, ...sourceLocation(source, button.opening), code, reason,
+    component: button.name, variant: button.variant, source: button.element.getText(source) });
+  if (source.parseDiagnostics.length) {
+    return { text, changes, findings: [{ file, line: 1, column: 1, code: 'parse-error', reason: ts.flattenDiagnosticMessageText(source.parseDiagnostics[0].messageText, '\n') }] };
+  }
+  const commits = buttons.filter(button => button.variant === 'primary' || button.intent === 'commit');
+  for (const button of buttons) {
+    if (button.shadowed) {
+      flag(button, 'shadowed-button-binding', 'A local binding shadows the Grammar import; inspect its actual component before migrating.');
+      continue;
+    }
+    const pending = [];
+    if (button.intent === 'commit' || button.variant === 'primary') {
+      if (button.repeated) pending.push(['commit-in-collection', 'A repeated item needs a human choice of alternative or neutral.']);
+      if (commits.some(other => other !== button && other.owner === button.owner && canCoexist(button, other))) pending.push(['multiple-commits', 'More than one commit can render in this component; choose the decision owner and next action.']);
+    }
+    if (button.props.has('intent') && !button.props.has('variant')) {
+      for (const [code, reason] of pending) flag(button, code, reason);
+      continue;
+    }
+    if (button.props.has('intent')) pending.push(['intent-and-variant', 'Existing intent and variant need a human reconciliation.']);
+    if (!button.props.has('variant')) pending.push(['missing-variant', 'No old variant declares the command role; choose its consequence and rank.']);
+    else if (button.variant === null) pending.push(['dynamic-variant', 'A dynamic variant needs a human intent for every branch.']);
+    else if (button.variant !== 'secondary' && !button.mapped) pending.push(['unknown-variant', 'This variant has no published mechanical intent mapping.']);
+    if (button.opening.attributes.properties.some(ts.isJsxSpreadAttribute)) pending.push(['spread-props', 'Spread props can supply or override intent, step or variant; inspect the source.']);
+    if (WEAK.has(button.variant) && destructiveSignal(button.element.getText(source))) pending.push(['destructive-verb', 'A destructive or negative command on a weak variant needs its actual consequence and confirmation step reviewed.']);
+    if (button.props.has('step')) pending.push(['existing-step', 'An existing destructive step needs reconciliation with the migrated intent.']);
+    if (pending.length) {
+      for (const [code, reason] of pending) flag(button, code, reason);
+      continue;
+    }
+    const intent = button.variant === 'secondary'
+      ? commits.some(other => other.group === button.group && canCoexist(button, other)) ? 'alternative' : 'neutral'
+      : button.mapped;
+    const step = button.variant === 'danger' ? 'confirm' : button.variant === 'danger-soft' ? 'entry' : null;
+    const attribute = button.props.get('variant');
+    const replacement = `intent="${intent}"${step ? ` step="${step}"` : ''}`;
+    edits.push({ start: attribute.getStart(source), end: attribute.end, replacement });
+    changes.push({ file, ...sourceLocation(source, button.opening), component: button.name, from: button.variant, intent, ...(step ? { step } : {}) });
+  }
+  let output = text;
+  for (const edit of edits.sort((first, second) => second.start - first.start)) output = output.slice(0, edit.start) + edit.replacement + output.slice(edit.end);
+  return { text: output, changes, findings };
+}
+
+function sourceFiles(directory) {
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) return GENERATED.has(entry.name) ? [] : sourceFiles(target);
+    return entry.isFile() && /\.[jt]sx$/i.test(entry.name) ? [target] : [];
+  }).sort();
+}
+
+/** Preview or apply safe migrations in one app's FE tree; every unresolved case is retained in the returned report. */
+export function migrateButtonIntent({ root, write = false, ts = loadTypescript(root, PACKAGE_ROOT) }) {
+  if (!ts) throw new Error('button-intent needs TypeScript installed in the app or @starci/hfs development checkout');
+  const frontend = path.join(root, 'fe');
+  if (!fs.statSync(frontend, { throwIfNoEntry: false })?.isDirectory()) throw new Error('button-intent runs at an app root with a fe/ directory');
+  const report = { schema: 'starci/button-intent-codemod@1', root, write, filesScanned: 0, filesChanged: [], changes: [], findings: [] };
+  for (const target of sourceFiles(frontend)) {
+    const file = path.relative(root, target).split(path.sep).join('/');
+    const original = fs.readFileSync(target, 'utf8');
+    const result = transformButtonIntent({ ts, text: original, file });
+    report.filesScanned += 1;
+    report.changes.push(...result.changes);
+    report.findings.push(...result.findings);
+    if (result.text !== original) {
+      report.filesChanged.push(file);
+      if (write) fs.writeFileSync(target, result.text);
+    }
+  }
+  return report;
+}
+
+const cell = value => String(value).replaceAll('|', '\\|').replaceAll('\n', ' ');
+
+/** Render the migration and human decision list as Markdown; JSON consumers use the same unabridged report object. */
+export function buttonIntentMarkdown(report) {
+  const lines = ['# Button intent migration', '', `${report.write ? 'Applied' : 'Dry run'}: ${report.changes.length} safe changes in ${report.filesChanged.length} files; ${report.findings.length} unresolved findings.`, '',
+    '## Safe changes', '', '| Location | Before | Intent | Step |', '| --- | --- | --- | --- |',
+    ...report.changes.map(change => `| ${cell(`${change.file}:${change.line}:${change.column}`)} | ${change.from} | ${change.intent} | ${change.step ?? ''} |`), '',
+    '## Human decisions', '', '| Location | Code | Reason |', '| --- | --- | --- |',
+    ...report.findings.map(finding => `| ${cell(`${finding.file}:${finding.line}:${finding.column}`)} | ${finding.code} | ${cell(finding.reason)} |`), ''];
+  return lines.join('\n');
+}
+
+function parse(argv) {
+  const [name, ...rest] = argv;
+  if (name !== 'button-intent') throw new Error('starci app codemod takes button-intent');
+  const options = { write: false, format: 'markdown' };
+  const args = rest.values();
+  for (const arg of args) {
+    const [flag, inline] = arg.split(/=(.*)/s);
+    if (flag === '--write' || flag === '--json') {
+      if (inline !== undefined && !['true', 'false'].includes(inline)) throw new Error(`${flag} expects true or false`);
+      const value = inline === undefined || inline === 'true';
+      if (flag === '--write') options.write = value;
+      else if (value) options.format = 'json';
+    } else if (flag === '--format' || flag === '--report') {
+      const value = inline ?? args.next().value;
+      if (!value || value.startsWith('--')) throw new Error(`${flag} needs a value`);
+      options[flag.slice(2)] = value;
+    } else throw new Error(`unknown codemod option ${arg}`);
+  }
+  if (!['json', 'markdown'].includes(options.format)) throw new Error('--format accepts json or markdown');
+  return options;
+}
+
+/** CLI boundary: dry-run by default, --write mutates only safe FE source; findings return exit 1 with a complete report. */
+export function codemodMain(argv, { cwd, stdout }) {
+  const options = parse(argv);
+  if (options.report && !/\.(?:json|md)$/i.test(options.report)) throw new Error('--report needs a .json or .md report file');
+  const report = migrateButtonIntent({ root: path.resolve(cwd), write: options.write });
+  const output = options.format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : buttonIntentMarkdown(report);
+  if (options.report) {
+    const target = path.resolve(cwd, options.report);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, output);
+  }
+  stdout(output);
+  return report.findings.length ? 1 : 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.35",
+  "version": "4.7.37",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "db/**",
     "ci/**",
     "coverage/**",
+    "codemod/**",
     "lint/**",
     "scaffold/**",
     "report/**",

package/runtime/knowledge/grammars/index.yaml

@@ -61,7 +61,16 @@ topics:
       shadow, one pink decision accent with a text-safe accent for text — with DNA, idioms, a
       mobile-first playbook for playful learning or consumer apps, and family boundaries including two
       decisions flagged for the family owner.
+  - id: heritage
+    path: heritage/DNA.yaml
+    title: Heritage Grammar
+    summary: |
+      Generated snapshot of the Heritage family's parity declaration, arrangement, scoped tokens and Common renderers.
 families:
+  - id: heritage
+    title: heritage
+    contractRef: common
+    packageSnapshot: heritage/DNA.yaml
   - id: common
     title: common
     componentContract:

package/runtime/knowledge/grammars/starci/playbook.yaml

@@ -132,7 +132,10 @@ shapes:
           `cancelLabel` in the product's words; `onConfirm` may return a promise, which keeps the confirm
           pending and the dialog open until it settles
       - renderer: Button
-        role: The trigger, inside the Core root; never a red Button (Core has no destructive variant)
+        role: |
+          The trigger, inside the Core root: `intent="destructive"` at the entry step, which resolves to
+          `danger-soft` (CTA-6); the confirm inside the AlertDialog is the solid `danger` confirm, dismiss
+          comes first and takes initial focus
     notes: |
       Initial focus lands on the cancel action and an outside press never dismisses. A reversible
       action is not a confirmation: act, then offer undo through a Toast `action`.
@@ -189,7 +192,8 @@ shapes:
         implements: [FE-APP-SHELL-2]
         compose: |
           IdentityLockup sits inside PlainPressable size="control". Its square logo mark has a
-          transparent background, no radius and object-fit contain, with a monogram fallback. The title
+          transparent background, no radius and object-fit contain; without an image it uses Avatar's
+          bundled DiceBear initials. The title
           has a muted role subtitle and no caret. PlainPressable has no button shape or hover effect;
           press uses scale(0.96), focus remains visible and reduced motion removes the zoom.
       - id: navbar-right-cluster
@@ -199,7 +203,9 @@ shapes:
           single-select DropdownMenu, Switch size="control" with sun/moon size-5 thumb icons and
           isLabelHidden, a bell IconButton with count badge opening Popover, then a circle-only
           AvatarButton size="control" opening the account DropdownMenu. AvatarButton uses uploaded src
-          first and otherwise a DiceBear fallback seeded by userId. DropdownMenu preserves HeroUI's
+          first and otherwise the bundled DiceBear initials style: the first and last words of name
+          supply the letters, and userId passed as seed determines colour, falling back to name when
+          seed is absent (owner:avatar-default-dicebear-initials). DropdownMenu preserves HeroUI's
           anatomy and default selection indicator. The supported language labels use the "Vietnamese"
           and "English" entries in modules/i18n/messages/app-shell.yaml; each language keeps its autonym.
       - id: account-menu
@@ -245,9 +251,12 @@ shapes:
           when those categories exist in the product; labels come from modules/i18n/messages/ui.yaml
           and modules/i18n/messages/app-shell.yaml. ListBox panel alignment keeps rows and section
           captions on the same content edge without padding wrappers. A row shows avatar, name,
-          trailing time, last message and unread badge; the open row is highlighted. Group identity
-          uses AvatarGroup layout="grid": a 2×2 composite with the first three members and a +N
-          overflow count when more than four exist, plus a group icon before the name.
+          trailing time, last message and unread badge; the open row is selected through HeroUI.
+          The name and preview each occupy one line with an ellipsis, and the title carries no group
+          glyph (owner:item-description-one-line). Pass emphasis="unread" for unread rows so Grammar
+          strengthens the label and preview; read rows keep the vendor label and muted preview.
+          Group identity uses AvatarGroup layout="grid" with the member/count arrangement declared
+          by presentation.groupIdentity.
     notes: |
       FE-RULE-OWNERSHIP in knowledge/patterns/fe/index.yaml separates universal app-shell semantics
       from these family APIs, values, shapes and effects. @starci/eslint-grammar-starci owns their
@@ -463,6 +472,16 @@ guidance:
       in a component.
 
 presentation:
+  collectionItems:
+    ownership: FE-RULE-OWNERSHIP
+    requirement: |
+      ListBoxItem, DropdownMenuItem, SidebarItem and the ListOption shared by Select and ComboBox
+      render descriptions in HeroUI's Description slot. The family DNA's collectionItem.descriptionLines
+      defaults to one line with an ellipsis (owner:item-description-one-line); descriptionLines accepts
+      1, 2 or 3 for a bounded override through the packaged stylesheet's line clamp. The complete
+      description remains available to assistive technology. ListBoxItem emphasis="unread" uses
+      collectionItem.unreadWeight for both label and description; omit it for HeroUI's read treatment.
+      labelLeading remains an optional decorative title slot, separate from conversation identity.
   glyphs:
     ownership: FE-RULE-OWNERSHIP
     implements: FE-ICON
@@ -478,13 +497,23 @@ presentation:
     implements: COLLECTION-3
     requirement: |
       Compose AvatarGroup layout="grid" at one Avatar size, including size="control". Two members
-      split the round mark; three show one member above two below; four occupy a 2 by 2 grid. A hairline
-      separates cells. Above four members the first three remain visible and the fourth cell shows
-      the remaining-member count as +N. Each member uses Avatar's image, initials or DiceBear fallback.
-      A single person uses Avatar. Pass the uploaded avatar as `src`; otherwise pass the user or identity
-      id as `seed` on Avatar, AvatarButton or each AvatarGroup member, and Grammar draws its fixed
-      deterministic DiceBear style; with neither, Grammar uses initials. Apps neither declare nor import
-      `@dicebear/*`. Apps supply member identity data; the renderer owns the geometry.
+      split the round mark; three show one member above two below; four occupy a 2 by 2 grid. Every cell
+      has a ring in the surface colour. At five or more members the first three remain visible and the
+      fourth cell shows the total member count, such as 5 or 30, through Avatar's shared fallback path.
+      The row layout keeps its +N count. overflowLabel receives the hidden-member count in both layouts
+      for accessible naming, while the grid digits show the total. A single person uses Avatar.
+      Pass an uploaded image as `src`; otherwise Grammar always draws the bundled DiceBear `initials`
+      style, with the first letter of the first word and the first letter of the last word of `name`
+      (one word supplies one letter). `seed`, the user or entity id, determines colour when present;
+      otherwise `name` does. The image clips to the Avatar shape, circle by default, and keeps text
+      contrast in both themes (owner:avatar-default-dicebear-initials).
+      Avatar, AvatarButton and each AvatarGroup member accept `kind="person" | "agent"`, default person.
+      An agent's name is free text and uses exactly the same initials rule, without role-suffix parsing.
+      `kind="agent"` adds a HeroUI Badge at the Avatar's bottom-right edge with a bot glyph, a surface-colour
+      ring and an accessible name containing AI (owner:agent-avatar-initials-bot-badge). The family hides
+      the badge below 32px, including the 16px to 24px cells in a 2 by 2 grid; the identity's accessible
+      name still includes AI. Apps neither declare nor import `@dicebear/*`. Apps supply member identity
+      data; the renderer owns the geometry.
   padding:
     ownership: FE-RULE-OWNERSHIP
     knowledge: knowledge/ui/presentation/padding.yaml
@@ -731,8 +760,10 @@ presentation:
             when: A Grammar list sits inside a panel or its rows own their own inset
             owner: "`SurfaceListCard` / `ListBox`"
             render: ListBox resolves inset="panel" in a surface nesting context, or callers select it explicitly. Its
-              list container extends into the panel gutter; items retain HeroUI's default padding, and row
-              backgrounds extend into that gutter. Its sections captions share the row content edge. Padding
+              row boxes align with the panel content edge, like the search field and tabs boxes, without
+              negative-margin bleed (owner:panel-list-box-edge). The list retains HeroUI p-1; items retain
+              px-2 py-1.5, rounded-2xl and mt-1 between items, with the same padding and radius for hover,
+              pressed and selected backgrounds. Section captions share the inset content edge. Padding
               wrappers with px-*, ps-* or pe-* stack this inset and fail FE_LIST_PANEL_PADDING in the universal
               FE canon (R318).
       - rule: PADDING-1

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -23,35 +23,35 @@ pins:
     source: packages/heroicons/package.json
     why: 'StarCi custom Heroicons-compatible cuts; eslint-grammar-starci (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
   '@starci/grammar':
-    version: 0.12.3
+    version: 0.12.4
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.44
+    version: 3.4.45
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.0.0
+    version: 9.1.0
     group: starci
     install: registry
     side: fe
     source: packages/eslint/fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-starci':
-    version: 0.12.3
+    version: 0.12.4
     group: starci
     install: registry
     side: fe
     source: packages/eslint/grammar-starci/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.12.3
+    version: 0.12.4
     group: starci
     install: registry
     side: fe
@@ -91,14 +91,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.35
+    version: 1.7.37
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.35
+    version: 4.7.37
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/fe-stack.yaml

@@ -121,10 +121,11 @@ concerns:
     pattern: FE-UI
     forbids: ['@dicebear/*', boring-avatars, 'react-nice-avatar', multiavatar]
     why: >-
-      Grammar owns circle avatars: pass the uploaded avatar as src, otherwise pass the user or identity id as seed on
-      Avatar, AvatarButton or AvatarGroup members. Grammar renders deterministic DiceBear images with its fixed DNA style;
-      @dicebear/core and @dicebear/styles are Grammar runtime dependencies pinned in canon-pins.yaml. Apps declare and
-      import @starci/grammar, never @dicebear/*, and draw no avatar visuals. With neither src nor seed, initials remain.
+      Grammar owns avatars: pass the uploaded avatar as src and the user or identity id as seed on Avatar, AvatarButton
+      or AvatarGroup members. Without src, Grammar renders bundled DiceBear initials using the first and last words of
+      name, with colour seeded by seed when present and by name otherwise. kind="agent" adds the Grammar-owned bot badge
+      without changing the name rule. @dicebear/core and @dicebear/styles are Grammar runtime dependencies pinned in
+      canon-pins.yaml. Apps declare and import @starci/grammar, never @dicebear/*, and draw no avatar visuals.
   - id: theme
     tier: core
     packages: [next-themes]