@starci/hfs 4.7.35 → 4.7.36

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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 +13,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.36",
   "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.36
     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.36
     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]

package/runtime/knowledge/hfs/rules.yaml

@@ -5598,3 +5598,33 @@ rules:
         source: owner
         quote: "apps on Grammar write layout-only CSS; every visual element lives in @starci/grammar"
         ruling: "ANATOMY-2 owns contextual field defaults, PADDING-0 owns panel list alignment, and COLLECTION-3 owns composite member avatars for conversation and group identity. Grammar supplies these capabilities; the FE canon rejects static field variants on either layer, primary Tabs inside painted surfaces, raw app surface paint and stacked horizontal list-wrapper padding inside painted surfaces."
+
+  - id: R319
+    code: "FE_BUTTON_INTENT"
+    law: "An app Button or IconButton declares an intent and never a variant; Grammar resolves the variant from intent and placement (CTA-6). A destructive confirm lives in a confirmation dialog, a render holds at most one commit, and a collection item holds none."
+    kinds: [codemod, lint, design]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_BUTTON_INTENT", "FE_BUTTON_INTENT_REQUIRED", "FE_BUTTON_NO_VARIANT", "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG", "FE_SINGLE_COMMIT_PER_RENDER", "FE_NO_COMMIT_IN_COLLECTION_ITEM"]
+    enforcers:
+      - {kind: eslint-fe, id: button-intent-required}
+      - {kind: eslint-fe, id: button-no-variant}
+      - {kind: eslint-fe, id: destructive-confirm-in-dialog}
+      - {kind: eslint-fe, id: single-commit-per-render}
+      - {kind: eslint-fe, id: no-commit-in-collection-item}
+    editions: [lite, full]
+    docs:
+      - knowledge/ui/composition/cta.yaml
+      - docs/code-pattern-enforcement.md#r319-button-intent
+    proves:
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+    exemplifiedBy:
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+    witness:
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+    templateNa: "The intent of an action comes from the product decision in the .starciwork specification; a template cannot choose it."
+    cases:
+      - id: case-1
+        date: "2026-10-25"
+        source: owner
+        quote: "Critique this carefully so the button choice is a system and not a feeling, understand? Update .claude."
+        ruling: "The button variant follows the declared intent (owner ruling button-variant-follows-intent): the app passes intent and step, Grammar derives the variant from them and from the placement it reads from React context. The semantics are HeroUI's, so the lint is universal in the FE canon."