@ryuenn3123/agentic-senior-core 4.3.7 → 4.3.9

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

@@ -1,167 +0,0 @@
-/**
- * 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 dossier from
- * `.agent-context/prompts/research-design.md`:
- *   - categoryCodes (Section 3a)
- *   - anchorReference (Section 3b)
- *   - creativeCommitments (Section 3c)
- */
-
-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,
-      preferSpecificOverGeneric: 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: [
-      'premium-interactive-web-experiences',
-      'cinematic-campaign-and-product-launch', 
-      'contemporary-editorial-digital-design',
-      'cinematic-behavior-and-transition-systems',
-      'experimental-editorial-structure',
-      'complex-physical-engineering',
-      'material-artifacts-and-instruments',
-      'workflow-and-custody-systems',
-    ],
-    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',
-        'categoryDefaultReason',
-        'rejectionNote',
-      ],
-      forbiddenPlaceholderPhrases: [
-        'clean typography',
-        'modern color palette',
-        'smooth animations',
-        'best practices',
-        'good design',
-      ],
-      candidateEntries: [],
-    },
-
-    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',
-      ],
-    },
-  };
-}

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

@@ -1,211 +0,0 @@
-/**
- * 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

@@ -1,79 +0,0 @@
-/**
- * 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

@@ -1,64 +0,0 @@
-/**
- * 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',
-];