@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/lib/cli/memory-continuity.mjs

@@ -1,3 +1,4 @@
+// @file-size-exception: Multiple memory passes (normalize + redact + index + hydrate); planned for split in Phase 1.
 /**
  * Cross-agent memory continuity utilities.
  * Provides provider-agnostic observation normalization, privacy redaction,

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

@@ -0,0 +1,165 @@
+/**
+ * Research-dossier migration helper.
+ *
+ * Adds the `researchDossier.metadata` block to existing `docs/design-intent.json`
+ * files when it is absent, populating `antiRepeatLedger` from the existing
+ * conceptual anchor, palette, and motion fields so future UI work cannot
+ * unknowingly repeat shipped direction.
+ *
+ * Idempotent: if the metadata block already exists, the file is left untouched.
+ * Additive: never overwrites existing fields.
+ */
+
+import fs from 'node:fs/promises';
+
+import { pathExists } from '../../utils.mjs';
+
+const FRESHNESS_WINDOW_DAYS = 90;
+const FRESHNESS_RULE = 'Research dossier is stale when researchVerifiedAt is null or older than freshnessWindowDays. Stale dossiers must run research-design.md before UI implementation. User-explicit redesign requests bypass freshness and force fresh research regardless of age.';
+
+function takeFirstNonEmpty(...candidateValues) {
+  for (const candidateValue of candidateValues) {
+    if (typeof candidateValue === 'string' && candidateValue.trim().length > 0) {
+      return candidateValue.trim();
+    }
+  }
+  return null;
+}
+
+function buildPreviousAnchorEntry(designIntentContract) {
+  const conceptualAnchor = designIntentContract?.conceptualAnchor;
+  if (!conceptualAnchor || typeof conceptualAnchor !== 'object') {
+    return [];
+  }
+  const anchorReference = takeFirstNonEmpty(conceptualAnchor.anchorReference);
+  if (!anchorReference || anchorReference === 'agent-defined-anchor-reference') {
+    return [];
+  }
+  const specificReferencePoint = takeFirstNonEmpty(conceptualAnchor.specificReferencePoint);
+  const summary = specificReferencePoint
+    ? `${anchorReference} (${specificReferencePoint})`
+    : anchorReference;
+  return [{
+    summary,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-direction',
+  }];
+}
+
+function buildPreviousPaletteEntry(designIntentContract) {
+  const derivedTokenLogic = designIntentContract?.derivedTokenLogic;
+  const colorTruth = designIntentContract?.colorTruth;
+  const colorDerivationSummary = takeFirstNonEmpty(derivedTokenLogic?.colorDerivationSource);
+  const colorIntent = takeFirstNonEmpty(colorTruth?.intent);
+  const summary = takeFirstNonEmpty(colorIntent, colorDerivationSummary);
+  if (!summary) {
+    return [];
+  }
+  return [{
+    summary,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-palette-behavior',
+  }];
+}
+
+function buildPreviousMotionEntry(designIntentContract) {
+  const motionPaletteDecision = designIntentContract?.motionPaletteDecision;
+  const motionSystem = designIntentContract?.motionSystem;
+  const derivedTokenLogic = designIntentContract?.derivedTokenLogic;
+
+  const motionSignature = takeFirstNonEmpty(
+    motionPaletteDecision?.signatureMotion,
+    motionPaletteDecision?.motion,
+    motionSystem?.signature,
+    motionSystem?.purpose,
+    derivedTokenLogic?.motionBudget,
+  );
+  if (!motionSignature) {
+    return [];
+  }
+  return [{
+    summary: motionSignature,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-motion-signature',
+  }];
+}
+
+export function buildResearchDossierMetadata({
+  designIntentContract = null,
+  populateLedgerFromExistingContract = false,
+} = {}) {
+  const metadata = {
+    researchVerifiedAt: null,
+    freshnessWindowDays: FRESHNESS_WINDOW_DAYS,
+    freshnessRule: FRESHNESS_RULE,
+    antiRepeatLedger: {
+      blocklistFromHistory: true,
+      ledgerScope: 'signature-level-descriptors-only',
+      ledgerMaxEntriesPerCategory: 3,
+      previousAnchors: [],
+      previousPalettes: [],
+      previousMotionSignatures: [],
+    },
+    userExplicitRedesignBypassesFreshness: true,
+    statusAwareValidation: {
+      seedStatuses: [
+        'seed-needs-design-synthesis',
+        'seed-generated-during-init',
+        'seed-generated-during-upgrade',
+      ],
+      seedSkipsDossierShape: true,
+      activeRequiresFreshOrExplicitRedesign: true,
+    },
+  };
+
+  if (populateLedgerFromExistingContract && designIntentContract && typeof designIntentContract === 'object') {
+    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);
+  }
+
+  return metadata;
+}
+
+/**
+ * Migrates an existing design-intent.json file in place by adding
+ * `researchDossier.metadata` when absent. Idempotent.
+ *
+ * @param {string} designIntentFilePath
+ * @returns {Promise<{ migrated: boolean, reason: string }>}
+ */
+export async function migrateExistingDesignIntentToResearchDossierSchema(designIntentFilePath) {
+  if (!(await pathExists(designIntentFilePath))) {
+    return { migrated: false, reason: 'design-intent-file-absent' };
+  }
+
+  const fileContent = await fs.readFile(designIntentFilePath, 'utf8');
+  let designIntentContract;
+  try {
+    designIntentContract = JSON.parse(fileContent);
+  } catch {
+    return { migrated: false, reason: 'design-intent-file-not-valid-json' };
+  }
+
+  if (!designIntentContract || typeof designIntentContract !== 'object') {
+    return { migrated: false, reason: 'design-intent-file-not-an-object' };
+  }
+
+  const existingResearchDossier = designIntentContract.researchDossier;
+  if (existingResearchDossier && typeof existingResearchDossier === 'object' && existingResearchDossier.metadata) {
+    return { migrated: false, reason: 'research-dossier-metadata-already-present' };
+  }
+
+  const populatedMetadata = buildResearchDossierMetadata({
+    designIntentContract,
+    populateLedgerFromExistingContract: true,
+  });
+
+  designIntentContract.researchDossier = {
+    ...(existingResearchDossier && typeof existingResearchDossier === 'object' ? existingResearchDossier : {}),
+    metadata: populatedMetadata,
+  };
+
+  await fs.writeFile(designIntentFilePath, `${JSON.stringify(designIntentContract, null, 2)}\n`, 'utf8');
+  return { migrated: true, reason: 'research-dossier-metadata-injected' };
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Audit policy sections of the design intent contract: AI-safe UI audit,
+ * production content policy, motion-palette decision contract, and the
+ * accessibility policy. These are the gates that fire before UI implementation.
+ */
+
+export function buildMotionPaletteDecisionSection() {
+  return {
+    productCategorySignal: 'agent-inferred-starting-heuristic',
+    densityDecisionSource: 'Choose motion density from task, content, brand, device, performance, and accessibility. Categories are heuristics.',
+    requiredInteractionStates: ['default', 'hover', 'focus-visible', 'active', 'disabled', 'loading', 'empty', 'error', 'success', 'transition'],
+    paletteAutopilotRisks: ['dark-slate-default', 'cream-beige-default', 'purple-blue-gradient-default', 'monochrome-template-default', 'uniform-card-surface-default', 'generic-grid-wallpaper-default', 'generic-line-wallpaper-default', 'calibration-mark-wallpaper-default', 'soft-glow-ai-template-default', 'cyber-neon-terminal-default'],
+    spatialDecision: 'State 3D/canvas/WebGL fit. If omitted, name product-fit reason and replacement interaction quality.',
+  };
+}
+
+export function buildAiSafeUiAuditSection({ projectName }) {
+  return {
+    status: 'agent-must-complete-before-ui-implementation',
+    failureDefinition: 'AI-safe UI uses template cards, generic marks, decorative grid or line wallpaper, calibration-mark wallpaper, test/demo/placeholder copy, terminal-only user paths, safe palettes, glow backgrounds, or copied scaffold composition.',
+    interchangeabilityTest: `If this UI can be renamed from ${projectName} to another product category without changing composition, palette, iconography, and motion, revise it.`,
+    requiredProductSpecificSignals: [
+      'agent-defined-product-specific-data-treatment',
+      'agent-defined-product-specific-motion-or-state-behavior',
+      'agent-defined-product-specific-morphology-iconography-or-spatial-structure',
+    ],
+    paletteExplorationRule: 'Use a visually exploratory product-derived palette with WCAG contrast and status clarity.',
+    backgroundPatternRule: 'Lines, grids, scanlines, noise, glows, blobs, logos, calibration marks, and geometry must serve a named product function; never use grid, line, or calibration-mark backgrounds as first-output filler. Measurement and inspection marks belong to task overlays or controls, not page wallpaper.',
+    aiColorAudit: {
+      status: 'agent-must-complete-before-ui-implementation',
+      failureDefinition: 'AI color drift uses safe defaults before deriving roles from the product anchor.',
+      autopilotRisks: ['cream-editorial-default', 'dark-slate-dashboard-default', 'purple-blue-gradient-default', 'monochrome-minimal-default', 'cyber-neon-terminal-default', 'soft-glow-atmosphere-default'],
+      requiredEvidence: [
+        'anchor-derived-color-logic',
+        'semantic-role-contrast-beyond-surface-decoration',
+        'product-specific-color-behavior-that-would-not-transfer',
+      ],
+      reviewQuestion: 'Why does this palette belong to this product?',
+    },
+    motionSpatialCourageAudit: {
+      status: 'agent-must-complete-before-ui-implementation',
+      defaultStance: 'Treat motion, scroll choreography, canvas, WebGL, and 3D as first-class options.',
+      requiredDecisionFields: [
+        'signature-motion-or-interaction',
+        'spatial-or-3d-fit',
+        'performance-and-reduced-motion-fallback',
+      ],
+      rejectionRule: 'State a product reason and replacement interaction quality before omitting 3D/canvas. Package count or vague performance fear is not enough.',
+      reviewQuestion: 'Is the interaction as expressive as the product can responsibly support?',
+    },
+    reviewQuestion: 'What visible evidence proves this is product-specific?',
+    blockingByDefault: true,
+  };
+}
+
+export function buildProductionContentPolicySection() {
+  return {
+    status: 'agent-must-complete-before-ui-implementation',
+    userFacingCopyRule: 'Visible UI copy must be product-ready and task-specific. Do not ship testing, demo, sample, placeholder, lorem, TODO, coming soon, or scaffold labels unless they are real product states.',
+    terminalDependencyRule: 'User-facing workflows must be operable through the UI unless the product is explicitly a CLI, developer tool, or operational runbook. Terminal commands belong in setup and deployment docs, not as the only path for core user tasks.',
+    allowedExceptions: [
+      'test-harness-only',
+      'documented-empty-state',
+      'admin-or-devtool-diagnostic-surface',
+      'explicit-user-requested-prototype',
+    ],
+    reviewQuestion: 'Can this UI be shipped to real users without removing test/demo copy or terminal-only workflow dependencies?',
+    blockingByDefault: true,
+  };
+}
+
+export function buildAccessibilityPolicySection() {
+  return {
+    hardComplianceFloor: 'WCAG-2.2-AA',
+    advisoryContrastModel: 'APCA',
+    failOnHardViolations: true,
+    advisoryFindingsDoNotBlockByDefault: true,
+    hardRequirements: {
+      textContrastMinimum: true,
+      nonTextContrast: true,
+      useOfColorOnlyProhibited: true,
+      focusVisible: true,
+      focusAppearance: true,
+      targetSizeMinimum: true,
+      keyboardAccess: true,
+      reflowRequired: true,
+      accessibleAuthenticationMinimum: true,
+      statusMessagesAndDynamicStateAccess: true,
+    },
+    advisoryChecks: {
+      perceptualContrastReview: true,
+      darkModeContrastTuning: true,
+      typographyReadabilityTuning: true,
+    },
+  };
+}

package/lib/cli/project-scaffolder/design-contract/sections/conceptual-anchor.mjs

@@ -0,0 +1,233 @@
+/**
+ * Conceptual anchor section of the design intent contract. Encodes the rules
+ * that force agents to commit to a real-world reference, motion, and typography
+ * decision before UI implementation, instead of defaulting to spatial cliches.
+ *
+ * Carries the Section 3-5 dossier from
+ * `.agent-context/prompts/research-design.md`:
+ *   - categoryCodes (Section 3)
+ *   - morphologicalExploration (Section 4)
+ *   - anchorCandidates (Section 5)
+ */
+
+export function buildConceptualAnchorSection() {
+  return {
+    mode: 'required-when-no-external-research',
+    seedMode: 'selection-policy-only',
+    anchorReference: 'agent-defined-anchor-reference',
+    researchBrief: '.agent-context/prompts/research-design.md',
+    requiresAgentSelectionBeforeUiImplementation: true,
+    userResearchAbsencePolicy: {
+      userSuppliedResearchOnly: true,
+      scaffoldSeedDoesNotCountAsResearch: true,
+      priorUiDoesNotCountAsResearch: true,
+      requireAgentLedResearchWhenAvailable: true,
+    },
+    candidateSelectionPolicy: {
+      considerAtLeast: 3,
+      discardObviousCandidateCount: 2,
+      minimumCandidateDistance: 'high',
+      discardPredictableCandidates: true,
+      preferDistinctiveOverSafe: true,
+      doNotRevealHiddenCandidateList: true,
+      outputOnlyChosenAnchor: true,
+      avoidSpatialPlaceMetaphorByDefault: true,
+      preferMechanismOverPlace: true,
+    },
+    creativeCommitmentPolicy: {
+      requiredBeforeComplianceReview: true,
+      recordInDesignDocs: true,
+      requiredCommitmentFields: [
+        'specificReferencePoint',
+        'signatureMotion',
+        'typographicDecision',
+      ],
+      rejectGenericQualityWordsOnly: true,
+      specificityFloor: 'name-real-material-instrument-artifact-architecture-editorial-genre-cinematic-behavior-exhibition-system-scientific-apparatus-or-industrial-mechanism',
+    },
+    forbiddenFinalAnchorTerms: [
+      'dashboard',
+      'cards',
+      'admin-panel',
+      'saas-shell',
+      'minimalist-interface',
+      'safe-admin-layout',
+      'room',
+      'darkroom',
+      'counting-room',
+      'control-room',
+      'war-room',
+      'studio',
+      'lab',
+      'cockpit',
+      'command-center',
+    ],
+    sourceDomains: [
+      'complex-physical-engineering',
+      'cinematic-behavior-and-transition-systems',
+      'experimental-editorial-structure',
+      'scientific-instrumentation',
+      'workflow-and-custody-systems',
+      'material-artifacts-and-instruments',
+      'premium-interactive-web-experiences',
+    ],
+    visualRiskBudget: {
+      mode: 'high-distinctiveness-with-accessibility-and-performance-guardrails',
+      allowRichMotionAndMicroInteraction: true,
+      rejectTimidDefaultWhenAnchorSupportsExpressiveUi: true,
+      rejectDependencyFearAsDownshiftReason: true,
+      requireReducedMotionFallback: true,
+    },
+    literalTranslationPolicy: {
+      preferNonLiteralTranslation: true,
+      allowedLiteralUse: 'Only use literal anchor artifacts when they serve a named product function, control, state, or task overlay.',
+      forbiddenLiteralUse: 'Do not turn anchor artifacts into decorative wallpaper, required chrome, default texture, or unavoidable theme props.',
+    },
+    spatialAutopilotPolicy: {
+      forbiddenHabitTerms: ['room', 'darkroom', 'counting-room', 'control-room', 'war-room', 'studio', 'lab', 'cockpit', 'command-center'],
+      allowedOnlyWhen: 'The product has a real physical place model, operational environment, or user workflow that depends on that place metaphor.',
+      replacementPreference: 'Use artifacts, custody flows, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms.',
+      reviewQuestion: 'Could this anchor still work if the word "room" was removed? If not, revise before UI code.',
+    },
+    requiredDerivedAxes: [
+      'typography',
+      'morphology',
+      'motion',
+      'responsive-composition',
+    ],
+    categoryCodes: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 3',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      minimumEntries: 3,
+      specificityRule: 'A category code is only valid if a reader unfamiliar with the project can visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name.',
+      antiLeakageRule: 'Listing a cliche identifies a trap; it does not endorse an aesthetic. Examples in the brief are NOT target aesthetics for any project. Each category code must carry an explicit rejection note so the cliche cannot quietly become the target.',
+      failingExamples: [
+        'clean typography (too abstract, applies to anything)',
+        'modern color palette (not falsifiable)',
+        'smooth animations (describes nothing specific)',
+      ],
+      passingExamples: [
+        "children's storybook illustration site: hand-painted gouache textures with irregular hand-lettered titles, off-grid spreads with whitespace gutters, page-turn pacing rather than scroll (instantly recognizable as kids book category default)",
+        'luxury car configurator: full-bleed monochrome photography on black, ultra-thin sans-serif tracked wide, slow horizontal scroll with locked vertical alignment, micro-counters that tick instead of slide (instantly recognizable as luxury auto category default)',
+        'academic philosophy journal: high-contrast black-on-cream, book-class serif body at 11pt with generous leading, footnote markers with hover panels, numbered table-of-contents navigation, no hero imagery (instantly recognizable as academic journal category default)',
+      ],
+      passingExamplesPolicy: 'These examples illustrate the description format only. They are AI-defaultable cliches of their categories and must NOT be adopted as target aesthetics for any project.',
+      commonAiSafeClichesToReject: [
+        'dev-tool default: condensed tabular numerics with minimal chrome and monospace code blocks on dark slate background, sans-serif metadata at 11-12px, monochrome status dots, single-line settings rows',
+        'AI-startup landing default: purple-to-pink gradient hero with floating 3D glass cards, sans-serif display type at 700-900 weight, vague hero copy, three-up feature grid below the fold',
+        'health/wellness app default: mint accent on white surface with coral status indicators, rounded pill-shaped buttons, friendly sans-serif at high weight, soft drop shadows on cards',
+        'SaaS admin default: left-side icon-only nav, top utility bar, three-card KPI row above a single data table, neutral grey-on-white with one accent color, modal-driven detail flows',
+        'marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid',
+      ],
+      commonAiSafeClichesPolicy: 'If the project sits anywhere near one of these AI-safe defaults, the matching cliche must appear in candidateEntries with an explicit rejection note. Software products pattern-match one of these without intervention; naming the trap is required even when the trap is uncomfortable to admit.',
+      selfTestRule: 'Read each category code aloud to someone unfamiliar with the project. If they cannot visualize a specific aesthetic direction from the text alone, the code is too abstract; revise. If they say "that is basically the X cliche", the description is specific enough; the cliche then belongs on the reject list with a rejection note, not as a candidate target.',
+      requiredFieldsPerEntry: [
+        'description',
+        'specificityEvidence',
+        'categoryDefaultReason',
+        'rejectionNote',
+      ],
+      forbiddenPlaceholderPhrases: [
+        'clean typography',
+        'modern color palette',
+        'smooth animations',
+        'best practices',
+        'good design',
+      ],
+      candidateEntries: [],
+    },
+    morphologicalExploration: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 4',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      requiredMatrixShape: '5x5-or-6x5',
+      minimumDimensions: 5,
+      maximumDimensions: 6,
+      valuesPerDimension: 5,
+      forbidCategoryCodeValuesInMatrix: true,
+      requireSelectedCombination: true,
+      requireUncomfortableCombination: true,
+      uncomfortableCombinationRule: 'Highlight at least one combination that feels instinctively wrong or uncomfortable but can be argued with product logic. The uncomfortable combination proves the matrix actually spans the design space; if every combination feels safe, shippable, and unobjectionable, the matrix is clustering in the safe-creative zone.',
+      uncomfortableCombinationRequiredFields: [
+        'combinationLabel',
+        'discomfortReason',
+        'productLogicJustification',
+      ],
+      widenDimensionsWhenUncomfortableCombinationCannotBeProduced: true,
+      seedDimensions: [],
+      seedMatrix: [],
+      selectedCombination: null,
+      uncomfortableCombination: null,
+    },
+    anchorCandidates: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 5',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      requiredCandidateCount: 5,
+      requiredFieldsPerCandidate: [
+        'anchorReference',
+        'conceptualFamily',
+        'jobFit',
+        'hierarchyImplication',
+        'densityImplication',
+        'typeImplication',
+        'stateLanguage',
+        'motionImplication',
+        'whatItRulesOut',
+        'renameTest',
+        'categoryCodeOverlap',
+      ],
+      renameTest: {
+        mode: 'strengthened',
+        requiredTestCategoryCount: 3,
+        testCategoryDistanceRule: 'The three test categories must be remote from each other and from the actual product (for example, if the product is a health app, test against fintech dashboard, kids educational game, and industrial equipment monitoring console).',
+        testCategoryFreshnessRule: 'Pick fresh test categories per anchor. Reusing the same triple across every anchor lets the agent memorize the pass condition instead of stress-testing the anchor. The illustrative triple in testCategoryDistanceRule is not a fixed test set.',
+        verdictScoring: {
+          'STRONG PASS': 'UI still coherent in 0 of 3 renamed categories.',
+          PASS: 'UI still coherent in 1 of 3. Pass with note.',
+          REVISE: 'UI still coherent in 2 of 3. Anchor is too generic. Revise the anchor to add product-specific constraints until it fails in at least 2 of 3.',
+          DISCARD: 'UI still coherent in 3 of 3. Anchor is category-agnostic. Discard immediately.',
+        },
+        requireTestCategoriesRecordedInDossier: true,
+        auditableByHumanReviewer: true,
+        renameTestRequiredFields: [
+          'testCategories',
+          'results',
+          'verdict',
+        ],
+      },
+      categoryCodeOverlapRule: 'List any Section 3 category codes this candidate accidentally inherits, with reasoning.',
+      forbiddenSelectedVerdicts: ['DISCARD'],
+      requiredSelectedVerdicts: ['STRONG PASS', 'PASS'],
+      candidates: [],
+    },
+    finalAnchorContract: {
+      requiredFields: [
+        'name',
+        'anchorReference',
+        'agentResearchMode',
+        'sourceDomain',
+        'specificReferencePoint',
+        'rationale',
+        'signatureMotion',
+        'typographicDecision',
+        'derivedTokenLogic',
+        'visualRiskBudget',
+        'motionRiskBudget',
+        'cohesionChecks',
+      ],
+      derivedTokenLogicAxes: [
+        'morphology',
+        'motion',
+      ],
+      cohesionChecks: [
+        'no-dashboard-mental-model',
+        'motion-derived-from-anchor',
+      ],
+    },
+  };
+}