@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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

@@ -0,0 +1,211 @@
+/**
+ * Design execution and handoff sections of the design intent contract:
+ * execution policy gates, the structured handoff payload, the review rubric,
+ * and the context-hygiene rules that govern continuity across sessions.
+ */
+
+import { GENERICITY_DRIFT_SIGNALS, VALID_BOLD_SIGNALS } from '../signal-vocab.mjs';
+
+export function buildDesignExecutionPolicySection() {
+  return {
+    representationStrategy: 'surface-plan-v1',
+    seedRefinementRequiredBeforeUiImplementation: true,
+    requireSurfacePlan: true,
+    requireComponentGraph: true,
+    requireViewportMutationPlan: true,
+    requireInteractionStateMatrix: true,
+    requireContentPriorityMap: true,
+    requireTaskFlowNarrative: true,
+    requireSignatureMoveRationale: true,
+    requireCreativeCommitmentGate: true,
+    requireStructuredHandoff: true,
+    requireRepoEvidenceAlignment: true,
+    forbidScreenshotDependency: true,
+    separateRequiredOutcomesFromCandidateMoves: true,
+    forbidCandidateMovesAsLockedRequirements: true,
+    forbidLibraryThemeAsVisualAuthority: true,
+    forbidLiteralAnchorChromeWithoutProductFunction: true,
+    handoffFormatVersion: 'ui-handoff-v1',
+    requirePerSurfaceMutationOps: true,
+    forbidUniformSiblingSurfaceTreatment: true,
+    zeroBasedRedesignResetsPriorVisualsWhenRequested: true,
+    semanticReviewFocus: [
+      'distinctiveness-vs-genericity',
+      'contract-fidelity',
+      'hierarchy-and-task-priority',
+      'component-state-behavior',
+      'cross-viewport-mutation',
+    ],
+  };
+}
+
+export function buildDesignExecutionHandoffSection({ projectName, primaryDomain, mutationRules }) {
+  return {
+    version: 'ui-handoff-v1',
+    location: 'inline-design-intent',
+    status: 'seed-needs-refinement',
+    seedMode: 'structure-first-scaffold',
+    requiresTaskSpecificRefinement: true,
+    primaryExperienceGoal: `Define the main ${String(primaryDomain || 'product').toLowerCase()} journey for ${projectName} from repo evidence, brief, and docs.`,
+    surfacePlan: [
+      {
+        surfaceId: 'agent-defined-primary-experience',
+        role: 'primary-context-synthesized-by-agent',
+        goal: 'Choose the first task path from product evidence; reject template shells.',
+        antiPatterns: ['dashboard-default', 'scale-only-responsive-layout'],
+      },
+    ],
+    componentGraph: {
+      nodes: [
+        { id: 'primary-experience', role: 'agent-defined-primary', priority: 'high' },
+        { id: 'supporting-context', role: 'agent-defined-support', priority: 'medium' },
+      ],
+      edges: [
+        { from: 'primary-experience', to: 'supporting-context', relationship: 'task-priority-support' },
+      ],
+    },
+    contentPriorityMap: {
+      primary: ['agent-defined-core-task-or-reading-path'],
+      secondary: ['agent-defined-supporting-context'],
+      deferred: ['agent-defined-deferred-or-hidden-content'],
+    },
+    viewportMutationPlan: {
+      mobile: {
+        primaryOperation: 'agent-defined-mobile-recomposition',
+        requiredSurfaceActions: [
+          'choose-mobile-task-order',
+          'disclose-or-remove-low-priority-content',
+        ],
+        forbiddenPatterns: ['scale-only-shrink'],
+        rationale: mutationRules.mobile,
+      },
+      tablet: {
+        primaryOperation: 'agent-defined-tablet-regrouping',
+        requiredSurfaceActions: [
+          'define-medium-width-grouping',
+          'preserve-task-clarity',
+        ],
+        forbiddenPatterns: ['uniform-module-grid-without-role-change'],
+        rationale: mutationRules.tablet,
+      },
+      desktop: {
+        primaryOperation: 'agent-defined-desktop-composition',
+        requiredSurfaceActions: [
+          'use-space-to-improve-hierarchy',
+          'avoid-equalizing-unrelated-content',
+        ],
+        forbiddenPatterns: ['interchangeable-dashboard-or-landing-chrome'],
+        rationale: mutationRules.desktop,
+      },
+    },
+    interactionStateMatrix: [
+      {
+        componentId: 'primary-interaction',
+        states: ['default', 'hover', 'focus', 'loading', 'error'],
+        notes: 'Refine states from project language and anchor; reject anonymous panels.',
+      },
+    ],
+    expressionFlexibility: {
+      lockedOutcomes: [
+        'preserve-primary-user-goal',
+        'preserve-accessibility-floor',
+        'preserve-production-content-policy',
+        'preserve-forbidden-patterns',
+      ],
+      candidateSignatureMoves: [
+        'agent-defined-candidate-move-not-locked-until-refined',
+      ],
+      flexibleAxes: [
+        'palette-primitives',
+        'typeface-choice',
+        'surface-treatment',
+        'component-library-skin',
+        'motion-implementation',
+        'anchor-artifact-literalness',
+      ],
+      lockingRule: 'A candidate move becomes required only after repo evidence, product function, accessibility need, or explicit user approval makes it necessary.',
+    },
+    taskFlowNarrative: [
+      `Entry: start ${projectName} from real evidence, not a generic opener.`,
+      'Resolution: define proof, feedback, recovery, and next action.',
+    ],
+    visualResetStrategy: {
+      activatesWhenUserRequests: [
+        'redesign from zero',
+        'redesain dari 0',
+      ],
+      existingUiAllowedAs: ['content-evidence', 'behavior-evidence', 'asset-source-evidence'],
+      existingUiForbiddenAs: ['palette-source', 'layout-source', 'motion-source'],
+      requiredResetAxes: ['composition', 'hierarchy', 'motion-or-interaction', 'responsive-information-architecture'],
+    },
+    signatureMoveRationale: 'Choose one project-specific visual, motion, type, or interaction move.',
+    creativeCommitment: {
+      status: 'agent-must-complete-before-ui-implementation',
+      requiredFields: [
+        'specificReferencePoint',
+        'signatureMotion',
+        'typographicDecision',
+      ],
+      failureMode: 'generic quality words without a real-world reference fail',
+    },
+    implementationGuardrails: {
+      requireBuildFromHandoff: true,
+      requireGapNotesBeforeFallback: true,
+      forbidGenericLayoutFallbackWithoutReason: true,
+      requireLockedVsFlexibleDecisionReview: true,
+      forbidCandidateMoveHardcoding: true,
+      forbidTestingDemoCopyInUi: true,
+      forbidTerminalOnlyUserFlows: true,
+    },
+  };
+}
+
+export function buildReviewRubricSection() {
+  return {
+    version: 'ui-rubric-v1',
+    genericityAutoFail: true,
+    dimensions: [
+      { key: 'distinctiveness', blockingByDefault: true, question: 'Is the UI authored and product-specific?' },
+      { key: 'contractFidelity', blockingByDefault: true, question: 'Does the UI follow contract, priorities, and accessibility?' },
+      { key: 'visualConsistency', blockingByDefault: false, question: 'Do type, spacing, color, and states form one system?' },
+      { key: 'heuristicUxQuality', blockingByDefault: false, question: 'Does the UI preserve clarity, feedback, and confidence?' },
+      { key: 'motionDiscipline', blockingByDefault: false, question: 'Is motion purposeful, performant, reduced-motion-safe, and on-tone?' },
+    ],
+    genericitySignals: [...GENERICITY_DRIFT_SIGNALS],
+    validBoldSignals: [...VALID_BOLD_SIGNALS],
+    reportingRules: {
+      mustExplainGenericity: true,
+      mustSeparateTasteFromFailure: true,
+      contractFidelityOverridesPersonalTaste: true,
+    },
+  };
+}
+
+export function buildContextHygieneSection() {
+  return {
+    continuityMode: 'opt-in-only',
+    allowedSources: [
+      'current-repo-evidence',
+      'current-user-brief',
+      'current-project-docs',
+      'explicitly-approved-current-task-constraints',
+    ],
+    taintedSources: [
+      'prior-chat-visual-memory',
+      'unrelated-project-aesthetics',
+      'remembered-screenshots-without-current-approval',
+      'generic-template-recall',
+    ],
+    repoEvidenceOverridesMemory: true,
+    requireExplicitContinuityApproval: true,
+    forbidCarryoverWhenUnapproved: true,
+    approvedExternalConstraintUsage: 'Convert approved external constraints into current-project rules; do not imitate source surfaces.',
+    externalWebsiteReferencePolicy: 'Use outside websites for mechanics, constraints, and quality bar analysis only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
+    driftSignals: [
+      'palette-reused-without-brief-support',
+      'prior-ui-visual-dna-carried-into-reset-request',
+      'room-or-control-room-anchor-repeated-without-product-need',
+      'external-reference-copied-instead-of-translated',
+    ],
+  };
+}

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

@@ -0,0 +1,79 @@
+/**
+ * Lightweight seed-signal helpers used by the contract builder to fill in
+ * mathSystems, motion intent, and copy describing the project context. Kept
+ * separate so the contract builder file stays focused on assembly.
+ */
+
+export function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
+  const normalizedDomain = String(discoveryAnswers.primaryDomain || '').trim().toLowerCase();
+  const normalizedBlueprint = String(initContext.blueprintFileName || '').trim().toLowerCase();
+
+  const isUiDomain = normalizedDomain.includes('web')
+    || normalizedDomain.includes('mobile')
+    || normalizedDomain.includes('frontend')
+    || normalizedDomain.includes('fullstack')
+    || normalizedDomain.includes('ui');
+
+  const isBackendOnlyDomain = normalizedDomain.includes('api service')
+    || normalizedDomain.includes('cli tool')
+    || normalizedDomain.includes('library');
+
+  const blueprintLooksUi = normalizedBlueprint.includes('frontend')
+    || normalizedBlueprint.includes('landing')
+    || normalizedBlueprint.includes('ui');
+
+  if (isUiDomain) {
+    return true;
+  }
+
+  if (!isBackendOnlyDomain && blueprintLooksUi) {
+    return true;
+  }
+
+  return false;
+}
+
+export function buildStructureFirstSeedSignals({
+  projectName,
+  projectDescription,
+  primaryDomain,
+  supplementalFields = {},
+}) {
+  const normalizedDescription = String(projectDescription || '').trim();
+  const repoEvidenceSummary = supplementalFields?.repoEvidence?.designEvidenceSummary || null;
+  const hasRepoEvidence = Boolean(
+    repoEvidenceSummary
+    || (Array.isArray(supplementalFields?.repoEvidence?.workspaceUiEntries)
+      && supplementalFields.repoEvidence.workspaceUiEntries.length > 0),
+  );
+  const evidenceSourceLabel = hasRepoEvidence
+    ? 'current repo evidence, existing UI code, and the active brief'
+    : 'the active brief and any repo evidence available at synthesis time';
+  const projectContextLabel = normalizedDescription
+    ? `the product context "${normalizedDescription}"`
+    : 'the current product context';
+
+  return {
+    designPhilosophy: `Synthesize design for ${projectName || 'this project'} from ${evidenceSourceLabel}. Choose visual language, libraries, color, type, spacing, and interaction from ${projectContextLabel}; verify technology claims with official docs.`,
+    typographyScaleRatio: 'agent-calibrated-from-content-platform-and-readability',
+    baseGridUnit: 'agent-calibrated-from-platform-density-and-implementation-stack',
+    spacingPattern: 'agent-defined-from-task-flow-and-viewport-needs',
+    densityMode: 'agent-defined-from-user-task-device-and-content-pressure',
+    colorIntent: `Choose semantic palette roles from ${projectContextLabel}, repo evidence, and accessibility. Reject scaffold or SaaS palette defaults.`,
+    paletteRoles: ['agent-defined-semantic-roles'],
+    distinctiveMoves: [
+      'Choose one product-specific move from task, audience, content, repo evidence, and docs.',
+    ],
+    motionPurpose: 'Use expressive motion when it improves hierarchy, continuity, feedback, memorability, or confidence. Verify new motion libraries with official docs.',
+    componentMorphology: {
+      mobile: 'Recompose for touch, task priority, and constrained attention.',
+      tablet: 'Regroup surfaces for medium width without cloning desktop or mobile.',
+      desktop: 'Use space for hierarchy and scanability; avoid template grids.',
+    },
+    mutationRules: {
+      mobile: 'Reorder, merge, or disclose content for mobile. Reject scale-only shrink.',
+      tablet: 'Regroup for tablet instead of width-only desktop reduction.',
+      desktop: 'Use space intentionally; avoid equal-weight modules without evidence.',
+    },
+  };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * Vocabulary lists for genericity / forbidden / valid-bold drift signals used
+ * across the design contract. Kept in one file so additions and removals stay
+ * traceable.
+ */
+
+export const GENERICITY_DRIFT_SIGNALS = [
+  'offline-prescribed-style-used-as-final-direction',
+  'unresearched-library-or-framework-choice',
+  'missing-conceptual-anchor-without-external-research',
+  'visual-decisions-not-derived-from-conceptual-anchor',
+  'ai-safe-ui-template-look',
+  'ai-color-default-palette-without-product-role-behavior',
+  'brandless-clean-template-look',
+  'interchangeable-product-renaming-test-fails',
+  'decorative-grid-or-glow-wallpaper-without-product-function',
+  'decorative-line-or-calibration-wallpaper-without-product-function',
+  'measurement-or-calibration-marks-used-as-page-background',
+  'testing-demo-or-placeholder-copy-shipped-to-ui',
+  'terminal-only-user-flow-without-product-reason',
+  'safe-cream-slate-or-monochrome-palette-used-as-readability-excuse',
+  'generic-abstract-logo-or-iconography',
+  'timid-anchor-that-renames-dashboard-or-admin-shell',
+  'motion-suppressed-without-accessibility-or-performance-reason',
+  'motion-or-3d-omitted-from-fear-without-fit-analysis',
+  'modern-library-rejected-from-dependency-fear-without-tradeoff-analysis',
+  'component-library-selected-by-habit-without-product-fit',
+  'scale-only-responsive-layout',
+  'zero-based-redesign-kept-prior-visual-dna',
+  'restyle-instead-of-recomposition',
+  'literal-anchor-artifacts-used-as-required-ui-chrome',
+  'candidate-signature-move-treated-as-locked-implementation',
+  'library-theme-tokens-drive-visual-language',
+  'spatial-room-anchor-used-by-habit',
+  'place-metaphor-used-as-layout-model-without-product-function',
+  'external-website-reference-copied-as-style',
+  'tailwind-only-or-component-kit-used-as-neutrality-claim',
+  'framework-selected-by-familiarity-instead-of-evidence',
+  'manual-framework-scaffold-used-when-official-setup-fits',
+];
+
+export const FORBIDDEN_PATTERN_SIGNALS = [
+  ...GENERICITY_DRIFT_SIGNALS.filter((signal) => signal !== 'unresearched-library-or-framework-choice'),
+  'single-safe-typographic-family-without-role-contrast-or-rationale',
+];
+
+export const VALID_BOLD_SIGNALS = [
+  'single-cohesive-conceptual-anchor',
+  'high-variance-candidate-selection',
+  'context-derived-visual-direction',
+  'three-at-a-glance-product-specific-signals',
+  'visually-exploratory-accessible-palette-derived-from-product',
+  'audacious-accessible-palette-with-product-role-behavior',
+  'background-or-geometry-serves-product-function',
+  'motion-or-spatial-experience-derived-from-anchor',
+  'explicit-3d-canvas-fit-or-nonfit-decision',
+  'official-docs-backed-modern-library-choice',
+  'headless-or-component-primitive-restyled-to-product-language',
+  'responsive-recomposition-by-task-priority',
+  'purposeful-motion-with-reduced-motion-path',
+  'non-spatial-product-anchor-or-workflow-mechanism',
+  'official-scaffolder-used-for-supported-project-shape',
+  'framework-choice-compared-against-plausible-alternative',
+];