@ryuenn3123/agentic-senior-core 4.0.1 → 4.0.2

package/.agent-context/prompts/bootstrap-design.md

@@ -20,7 +20,8 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 5. Encode `repoEvidence.designEvidenceSummary` when onboarding or detector evidence exists.
 6. Keep both design docs synchronized after implementation.
 7. Complete the Section 3-5 gates from `research-design.md` before UI implementation: `conceptualAnchor.categoryCodes.candidateEntries`, `conceptualAnchor.morphologicalExploration` (selected and uncomfortable combinations), and `conceptualAnchor.anchorCandidates.candidates` (exactly five, each with the strengthened rename test recorded).
-8. After agent and user select an anchor, set `researchDossier.metadata.researchVerifiedAt` to today's ISO date and flip `status` from any seed value to `active`. This closes the freshness window for additive UI tasks within `freshnessWindowDays`.
+8. Set `derivedTokenLogic.tokenContinuityClassification` for each of typography, palette, motion, and spacing. Use `anchor-derived` only when the token choice is causally tied to the anchor's real-world reality. Use `continuity-retained` when the token is kept from a previous design iteration without re-derivation. Use `newly-introduced` when the token is fresh but not anchor-derived. If any token category is `continuity-retained`, the typography, palette, or motion entry in `researchDossier.metadata.antiRepeatLedger` stays as historical record, and the classification declares the retention is intentional with explicit rationale recorded in the matching `derivationSource` field.
+9. After agent and user select an anchor, set `researchDossier.metadata.researchVerifiedAt` to today's ISO date and flip `status` from any seed value to `active`. This closes the freshness window for additive UI tasks within `freshnessWindowDays`.
 ## Creative Commitment Gate
 Before broad compliance review or UI implementation, record an agent-chosen visual direction in both design docs:
 - one concrete real-world anchor reference

package/.agent-context/prompts/research-design.md

@@ -90,6 +90,23 @@ Self-test: read each category code aloud to someone unfamiliar with the project.
 
 Output: at least three category codes per product surface in `categoryCodes`. Each entry must pass the specificity self-test, must include the one-sentence reason that pattern is the default for the category, and must include an explicit one-sentence rejection note ("I will not ship this; here is the trap it sets") so the cliche cannot quietly become the target.
 
+### Dimensional split (mandatory)
+
+Category codes must be broken down by dimension. Do not collapse multiple dimensions into a single category-level cliche. Each cluster lists the patterns that the product category will default to without intervention.
+
+- `typographyClusters`: font family combinations that are the category default. Be explicit about font families. Name the actual trio or pair that this product's category currently defaults to, derived from live portfolio observation for THIS task. Do not anchor on examples from other categories or other timeframes.
+- `paletteClusters`: palette signatures that are the category default.
+- `layoutClusters`: layout patterns that are the category default.
+- `motionClusters`: motion signatures that are the category default.
+- `imageryClusters`: image style or visual treatment that is the category default.
+
+Self-check before proceeding to Section 4: do the typography choices the agent is about to commit to in `derivedTokenLogic` (or downstream token sections) overlap with any item in `typographyClusters`? If yes, the agent must either:
+
+1. Flag the typography as a continuity choice with an explicit rationale, set `derivedTokenLogic.tokenContinuityClassification.typography` to `continuity-retained`, and record the reason that font family swap is deferred. The previous typography ledger entry stays as historical record; the classification declares the retention is intentional. OR
+2. Revise the typography pick to escape the autopilot cluster and set `tokenContinuityClassification.typography` to `anchor-derived` only when the new choice is causally tied to the anchor's real-world reality.
+
+This self-check applies to every dimension, not only typography. Do not let an output token match a category-code item from the agent's own list without explicit (1) or (2) treatment per dimension. Pretending continuity is derivation is the failure mode this gate exists to prevent.
+
 ## Section 4 — Morphological Exploration
 
 A morphological matrix forces the design space to be explored beyond the first idea.

package/README.md

@@ -63,6 +63,8 @@ The intended behavior is agent-led, not offline-template-led:
 - Modern UI claims: research current-year libraries and patterns when relevant; 2026 work should use 2026 evidence, and future years should update automatically through agent research.
 - Anti-generic rule: avoid safe dashboard shells, admin panels, card grids, scale-only mobile layouts, and static no-motion interfaces unless the product context explicitly justifies them.
 
+UI design work runs a research dossier prompt (`.agent-context/prompts/research-design.md`) before the bootstrap prompt. The dossier captures product reading, reference intake, category cliches, a morphological matrix, and five anchor candidates with a strengthened rename test. The contract carries a 90-day `researchVerifiedAt` freshness gate and an anti-repeat ledger seeded from prior anchor, palette, motion, and typography choices on existing projects, so additive UI work within the freshness window skips the research stage while redesigns and stale dossiers re-run it.
+
 ---
 
 ## MCP Quick Setup (VS Code)

package/lib/cli/project-scaffolder/design-contract/research-dossier-migration.mjs

@@ -84,6 +84,28 @@ function buildPreviousMotionEntry(designIntentContract) {
   }];
 }
 
+function buildPreviousTypographyEntry(designIntentContract) {
+  if (!designIntentContract || typeof designIntentContract !== 'object') {
+    return [];
+  }
+  const tokenSystem = designIntentContract?.tokenSystem;
+  const typographyTokens = tokenSystem && typeof tokenSystem === 'object' ? tokenSystem.typographyTokens : null;
+  if (!typographyTokens || typeof typographyTokens !== 'object') {
+    return [];
+  }
+  const tokenEntries = Object.entries(typographyTokens)
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([role, value]) => `${role}: ${value.trim()}`);
+  if (tokenEntries.length === 0) {
+    return [];
+  }
+  return [{
+    summary: tokenEntries.join('; '),
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-typography-trio',
+  }];
+}
+
 export function buildResearchDossierMetadata({
   designIntentContract = null,
   populateLedgerFromExistingContract = false,
@@ -99,6 +121,7 @@ export function buildResearchDossierMetadata({
       previousAnchors: [],
       previousPalettes: [],
       previousMotionSignatures: [],
+      previousTypographyChoices: [],
     },
     userExplicitRedesignBypassesFreshness: true,
     statusAwareValidation: {
@@ -116,6 +139,7 @@ export function buildResearchDossierMetadata({
     metadata.antiRepeatLedger.previousAnchors = buildPreviousAnchorEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
     metadata.antiRepeatLedger.previousPalettes = buildPreviousPaletteEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
     metadata.antiRepeatLedger.previousMotionSignatures = buildPreviousMotionEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
+    metadata.antiRepeatLedger.previousTypographyChoices = buildPreviousTypographyEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
   }
 
   return metadata;

package/lib/cli/project-scaffolder/design-contract/validation/completeness.mjs

@@ -7,6 +7,15 @@
 
 import { hasNonEmptyString } from './helpers.mjs';
 
+const SEED_STATUSES = new Set([
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+]);
+const REQUIRED_TOKEN_CATEGORIES = ['typography', 'palette', 'motion', 'spacing'];
+const ACTIVE_CLASSIFICATION_VALUES = new Set(['anchor-derived', 'continuity-retained', 'newly-introduced']);
+const SEED_CLASSIFICATION_VALUES = new Set(['anchor-derived', 'continuity-retained', 'newly-introduced', 'pending-research']);
+
 export function validateDesignContractCompleteness(designIntentContract) {
   const validationIssues = [];
   const conceptualAnchor = designIntentContract?.conceptualAnchor;
@@ -47,6 +56,35 @@ export function validateDesignContractCompleteness(designIntentContract) {
     ) {
       validationIssues.push('designIntent.derivedTokenLogic.validationRule must require traceability to anchorReference.');
     }
+
+    const tokenContinuityClassification = derivedTokenLogic.tokenContinuityClassification;
+    const isSeedStatus = SEED_STATUSES.has(designIntentContract?.status);
+    const allowedClassificationValues = isSeedStatus ? SEED_CLASSIFICATION_VALUES : ACTIVE_CLASSIFICATION_VALUES;
+    if (!tokenContinuityClassification || typeof tokenContinuityClassification !== 'object') {
+      validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification must exist. Each token category (typography, palette, motion, spacing) must declare anchor-derived, continuity-retained, or newly-introduced (pending-research is allowed only on seed contracts).');
+    } else {
+      if (
+        !Array.isArray(tokenContinuityClassification.validValues)
+        || !tokenContinuityClassification.validValues.includes('anchor-derived')
+        || !tokenContinuityClassification.validValues.includes('continuity-retained')
+        || !tokenContinuityClassification.validValues.includes('newly-introduced')
+        || !tokenContinuityClassification.validValues.includes('pending-research')
+      ) {
+        validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification.validValues must include anchor-derived, continuity-retained, newly-introduced, and pending-research.');
+      }
+      if (!hasNonEmptyString(tokenContinuityClassification.rule)) {
+        validationIssues.push('designIntent.derivedTokenLogic.tokenContinuityClassification.rule must explain when each value applies.');
+      }
+      for (const tokenCategoryName of REQUIRED_TOKEN_CATEGORIES) {
+        const classifiedValue = tokenContinuityClassification[tokenCategoryName];
+        if (!allowedClassificationValues.has(classifiedValue)) {
+          const allowedLabel = isSeedStatus
+            ? 'anchor-derived, continuity-retained, newly-introduced, or pending-research'
+            : 'anchor-derived, continuity-retained, or newly-introduced';
+          validationIssues.push(`designIntent.derivedTokenLogic.tokenContinuityClassification.${tokenCategoryName} must be one of: ${allowedLabel}. Got: "${classifiedValue}".`);
+        }
+      }
+    }
   }
 
   if (!['verified', 'pending-verification', 'no-external-library-needed'].includes(designIntentContract?.libraryResearchStatus)) {

package/lib/cli/project-scaffolder/design-contract/validation/research-dossier-validators.mjs

@@ -12,7 +12,7 @@ const REQUIRED_SEED_STATUSES = [
   'seed-generated-during-init',
   'seed-generated-during-upgrade',
 ];
-const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures'];
+const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures', 'previousTypographyChoices'];
 
 function validateMetadataBaseShape(metadata, validationErrors) {
   if (

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -139,6 +139,14 @@ function buildDesignIntentContractObject({
       typeScaleMethod: 'Prefer fluid clamp() type scales when supported; name ratio, role contrast, balance/wrap behavior, and numeric typography needs.',
       motionBudget: 'Name micro, layout, entrance, easing, stagger, and reduced-motion budgets; prefer transform/opacity for high-frequency motion.',
       validationRule: 'Every semantic token role must trace to anchorReference; keep exact primitive values flexible unless locked by repo evidence, accessibility validation, implementation constraints, or explicit user approval.',
+      tokenContinuityClassification: {
+        typography: 'pending-research',
+        palette: 'pending-research',
+        motion: 'pending-research',
+        spacing: 'pending-research',
+        validValues: ['anchor-derived', 'continuity-retained', 'newly-introduced', 'pending-research'],
+        rule: 'For each token category, classify whether the choice is anchor-derived (causally tied to anchorReference real-world reality), continuity-retained (kept from a previous design iteration without re-derivation), or newly-introduced (fresh choice not tied to anchor). Continuity-retained is acceptable; pretending continuity is derivation is not.',
+      },
     },
     motionPaletteDecision: buildMotionPaletteDecisionSection(),
     aiSafeUiAudit: buildAiSafeUiAuditSection({ projectName }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/documentation-boundary-audit.mjs

@@ -74,6 +74,19 @@ const BOUNDARY_RULES = [
       'README.md',
     ],
     trigger(filePath) {
+      // Path-based exclusion: design-contract JSON shape lives under
+      // lib/cli/project-scaffolder/. Files like research-dossier-migration.mjs
+      // describe agent-prompt JSON contract migrations, not database schema
+      // or persistent-store migrations, so they must not trigger this boundary
+      // even when the filename contains the words "schema" or "migration".
+      // Tests for those design-contract migrations are excluded for the same
+      // reason.
+      if (filePath.startsWith('lib/cli/project-scaffolder/')) {
+        return false;
+      }
+      if (filePath.startsWith('tests/') && /research-dossier|design-contract/i.test(filePath)) {
+        return false;
+      }
       return !isDocumentationFilePath(filePath)
         && /(database|schema|migration|repository|sql|prisma|typeorm|knex)/i.test(filePath);
     },

package/scripts/release-gate/static-checks.mjs

@@ -79,7 +79,12 @@ export function runStaticReleaseChecks(results, diagnostics) {
         stackFileName: 'agent-decision-runtime.md',
         blueprintFileName: 'agent-decision-architecture.md',
       },
-      status: 'release-gate-seed-validation',
+      // Seed status so `tokenContinuityClassification: pending-research`
+      // is a valid placeholder. This probe asserts seed-shape completeness,
+      // not active-contract behavior; an agent or user fills the contract
+      // with anchor-derived / continuity-retained / newly-introduced once
+      // the dossier is filled.
+      status: 'seed-needs-design-synthesis',
     }));
     const designContractIssues = validateDesignContractCompleteness(designIntentSeed);
 

package/scripts/validate/config.mjs

@@ -376,6 +376,13 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'Anti-Repeat Ledger Gate',
       'previousAnchors',
       'previousMotionSignatures',
+      'Dimensional split',
+      'typographyClusters',
+      'paletteClusters',
+      'layoutClusters',
+      'motionClusters',
+      'imageryClusters',
+      'tokenContinuityClassification',
     ],
   },
   {