@ryuenn3123/agentic-senior-core 4.3.2 → 4.3.5

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

@@ -1,160 +0,0 @@
----
-inclusion: manual
----
-
-# Research-Design Brief
-
-Authoritative design-research execution contract for UI scope. Loaded by UI Design Mode after `bootstrap-design.md`. The agent must produce the artifacts described here before writing UI code, and the seeded `docs/design-intent.json` must contain the fields named in Section 5.
-
-This brief is a single document with five sections. Sections 1 and 2 set up the research. Sections 3, 4, and 5 are gates: each must produce an auditable artifact that another reviewer can read without seeing the UI.
-
-## Authority
-
-- Treat `.agent-context/` and current project docs as technical authority.
-- Treat `README.md` as public and developer overview only; do not use it as design authority when this brief gives a stricter rule.
-- Treat external websites, benchmark apps, prior chats, and unrelated-project memory as candidate evidence for constraints, mechanics, and quality bars only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
-- WCAG 2.2 AA is the hard compliance floor. APCA may be used only as advisory perceptual tuning.
-
-## Live Source Freshness Gate
-
-Run this gate before Section 2 whenever web search is available. Treat modernity as rolling-current: use the session's current date as the freshness reference, and prefer the newest stable evidence that is relevant to the product and implementation surface.
-
-Rules:
-
-- For browser capability, framework setup, UI library, animation, 3D, canvas, charting, styling, accessibility, and package/API claims, use current official documentation or primary release notes first. Do not use trend posts as implementation authority.
-- For design trend, category-code, visual-language, motion-pattern, typography, color, and interaction claims, prefer sources published or materially updated within the last 24 months from the current date. If stronger older evidence is used, label it `old-timeless` and restrict it to durable principles, not "current modern" claims.
-- For product-category defaults, observe the current live category for this task. Do not rely on old examples, old galleries, or remembered benchmark screenshots as proof of what the category defaults to now.
-- If web search is unavailable, set `sourceFreshnessStatus` to `pending-live-verification`; use repo evidence and user-provided material only, and do not claim a direction is current-year modern.
-- If sources disagree, choose by product fit, accessibility, browser/runtime support, maintainability, and implementation feasibility, then record the disagreement.
-- If the user provides a concept, treat it as a first-class constraint. Research should support, refine, or challenge that concept with evidence; it must not override the concept with generic trend defaults unless there is a concrete product, accessibility, technical, or evidence conflict.
-
-Output: `sourceFreshness` block with `freshnessAnchorDate`, `rollingLookbackMonths` (default 24 for trend evidence), `sourceFreshnessStatus`, `officialDocsRequiredFor`, `oldSourcePolicy`, `userConceptAdaptation`, and `disagreements[]`.
-
-Every important research claim must also appear in `evidenceTable[]` with:
-
-- `claim`
-- `sourceUrl`
-- `sourceType` (`official`, `primary`, `industry`, `opinion`, `old-timeless`, `repo-evidence`, `user-provided`)
-- `publishedOrUpdatedAt` when visible, otherwise `unknown`
-- `fetchedAt`
-- `confidence` (`high`, `medium`, `low`)
-- `decisionImpact`
-
-Research vocabulary is internal-only. Use `sourceFreshness`, `evidenceTable[]`, `researchDossier`, `anchor`, `categoryCodes`, `morphologicalExploration`, and `renameTest` to audit decisions, but do not expose those labels in UI copy, public-facing docs, section headings, or final user-facing rationale unless the user explicitly asks for the research trace.
-
-## Anti-Repeat Ledger Gate (read first)
-
-If `docs/design-intent.json` already exists and carries `researchDossier.metadata.antiRepeatLedger`, treat every entry under `previousAnchors`, `previousPalettes`, `previousMotionSignatures`, and `previousStructuralFingerprints` as a hard blocklist before producing any candidate in Sections 3-5.
-
-Rules:
-
-- The five Section 5 anchor candidates must each differ from every blocklisted entry on at least conceptual family, hierarchy implication, and motion implication.
-- Restating an existing direction with new wording is REVISE, not pass.
-- A user-explicit redesign request ("redesign from zero", "redesain dari 0", "ulang dari 0", "research ulang", or any explicit reset) bypasses the freshness gate but does not weaken the ledger; previously shipped direction stays blocklisted unless the user explicitly says "revive existing direction".
-- Ledger entries are signature-level descriptors, not raw token dumps; treat them as direction summaries.
-
-If the ledger is empty or `researchDossier.metadata.researchVerifiedAt` is null because the contract is a fresh seed, the ledger is informational only and does not add blocklist entries.
-
-## Section 1 — Product Reading
-
-Before any visual choice, write a structured product reading:
-
-- Product type and core verb (what the user does, not what the UI shows).
-- Three highest-stakes user moments, ordered by frequency.
-- Data shapes that dominate the screen (timeseries, ledger, list, document, control, telemetry, conversational, spatial, other).
-- Latency profile (real-time, soft real-time, batch, ambient).
-- Failure modes the UI must absorb visibly (partial, stale, optimistic, conflict, offline, permission, rate-limit, none).
-- Context of use (one-shot, sustained focus, glance-and-go, background monitor, shared display, embedded).
-- Known constraints (device, runtime, accessibility, regulatory, performance budget, brand continuity).
-
-Output: `productReading` block. Each field must be one sentence, evidence-backed from repo or brief. Speculation is not allowed; if a field is unknown, name it as such and stop until the user resolves it.
-
-## Default Detection Protocol
-
-Before fetching any reference, use the `productReading` output to derive search direction. Do not self-select from a fixed category list.
-
-1. **Name defaults.** Name three design directions the agent is most tempted to use for this brief. For each, write one sentence naming the specific visual pattern (layout, palette, density, motion, typography, composition).
-
-2. **Argue against each default.** For each default, write one sentence on why it would flatten what is specific about THIS product's core verb, data shape, or context of use. The argument must reference a `productReading` field, not a generic aesthetic opinion.
-
-3. **Derive search direction from the argument.** The rejection argument reveals what the product needs that the default cannot provide. Use that need as the search query for `web_search` and `web_fetch`. Search by the product's core characteristic pair (medium x intent), not by product category name. Example: core verb "demonstrate" + data shape "narrative" -> search "editorial portfolio interaction design" not "portfolio sites."
-
-4. **Cross-domain pull.** Identify one domain that shares the same interaction model but a different visual vocabulary. Pull one reference from there. Example: portfolio -> scientific publication, exhibition catalog, film press kit -- anything with "demonstrate body of work" as the core verb but a different surface expectation.
-
-5. **Gallery check.** Find state-of-the-art quality references for the derived direction by searching the web. CRITICAL: DO NOT use gallery homepages or discovery platforms as references. You must drill down to find a specific featured product/website, fetch THAT specific product's URL, and use it as evidence.
-
-DO NOT fetch: Wikipedia, Dribbble templates, or generic blog posts about "best UI design practices."
-
-For each reference: fetch the actual product page this session, record what mechanic or hierarchy is borrowed, and explicitly state what is NOT borrowed (palette, component skin, layout rhythm).
-
-If the anchor concept you're considering would make sense to someone from 1920, it's too archival. The anchor must be legible to someone who uses the web today.
-
-## Section 2 — Reference Intake
-
-Reference material is fuel for variance, not a style source.
-
-- Capture between three and seven references per dimension that needs exploration: hierarchy, density, type system, motion, state language, material logic, color behavior.
-- For each reference, record: source URL or citation, what is borrowed (mechanic, behavior, hierarchy, density, type pairing, motion choreography), and what is explicitly not borrowed (palette, component skin, layout rhythm, brand posture).
-- References live in `referenceIntake[]`. The agent may not select an anchor in Section 5 that copies a reference's surface; only the borrowed mechanic is allowed to flow downstream.
-
-If references are not provided by the user and web search is unavailable, set `referenceIntakeStatus` to `internal-evidence-only` and constrain Sections 3 to 5 to repo evidence and project docs.
-
-## Section 3 — Creative Direction
-
-Before UI code, commit to a specific visual direction. The agent tends to converge toward generic, "on distribution" outputs. In frontend design this creates what users call the "AI slop" aesthetic. This section exists to prevent that.
-
-### 3a. Category defaults to avoid
-
-Name at least three specific cliches your product category will fall into without intervention. Be specific enough that someone unfamiliar with the project can visualize the exact aesthetic trap from the text alone.
-
-Common AI-safe cliches to name and reject when your product sits anywhere near them:
-
-- `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`
-- `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`
-- `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`
-- `marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid`
-
-Each category default must include a one-sentence rejection note explaining the trap it sets.
-
-Output: `categoryCodes[]` with at least three entries in `docs/design-intent.json`. Each entry has `description`, `categoryDefaultReason`, and `rejectionNote`.
-
-### 3b. Anchor reference
-
-Pick one concrete, googleable real-world reference whose mechanics (not surface) translate to your UI. The anchor must be specific enough that renaming the product to a different category breaks coherence.
-
-Hard constraints:
-- Reject generic quality words as anchors: "modern", "clean", "premium", "expressive", "minimal", "bold", "futuristic", "elegant" are not anchors.
-- Specific premium digital products are valid anchors when the borrowed element is an interaction mechanic, hierarchy pattern, or motion behavior -- not a palette or brand.
-- Do not default to spatial place metaphors (room, darkroom, control room, studio, lab, cockpit, command center). Prefer artifacts, workflows, instruments, data behaviors, materials, editorial systems, or interaction mechanisms.
-- Draw from IDE themes, cultural aesthetics, cinematic campaigns, editorial systems, material artifacts, or specific product experiences for inspiration.
-
-Output: `conceptualAnchor.anchorReference` in `docs/design-intent.json`.
-
-### 3c. Four creative commitments (record before coding)
-
-1. **Typography**: Choose distinctive fonts with meaningful role contrast. Avoid overused families (Inter, Roboto, Arial, Space Grotesk, system fonts). Pick choices that elevate the aesthetic. Record one variable-axis or pairing decision.
-2. **Color and palette**: Commit to a cohesive product-derived palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Name what product evidence makes the palette fit and one color behavior that would not transfer to another category.
-3. **Motion and interaction**: Define one signature motion behavior more specific than "smooth." Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use CSS-only or a modern motion library.
-4. **Composition**: Make one composition choice that avoids interchangeable card stacks. Create atmosphere and depth rather than defaulting to solid backgrounds.
-
-Avoid generic AI-generated aesthetics:
-- Overused font families and cliched color schemes (particularly purple gradients)
-- Predictable layouts and cookie-cutter component patterns
-- Solid-color backgrounds without atmosphere or depth
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. The agent still tends to converge on common choices across generations; resist this.
-
-Output: Record all four commitments in `docs/design-intent.json` before UI code. The `derivedTokenLogic.tokenContinuityClassification` must classify each of typography, palette, motion, and spacing as `anchor-derived`, `continuity-retained`, or `newly-introduced` with rationale.
-
-## Done Criteria
-
-The brief is complete when:
-
-1. `productReading` is filled with evidence-backed sentences.
-2. `referenceIntake[]` records the borrowed mechanic and the explicit non-copy boundary per reference (or `referenceIntakeStatus: internal-evidence-only` is set).
-3. `categoryCodes[]` has at least three entries with rejection notes.
-4. One anchor reference is recorded that passes the specificity test (renaming the product to a different category breaks coherence).
-5. Four creative commitments are recorded with product-derived rationale.
-6. Generic anchors and spatial-place defaults are rejected with the rejection reason recorded.
-
-Only after the brief is complete does the agent move on to `docs/DESIGN.md` and the rest of `docs/design-intent.json` (token logic, motion budget, accessibility policy, review rubric, library decisions, etc., per `bootstrap-design.md`).

package/lib/cli/commands/upgrade/design-intent-seed.mjs

@@ -1,46 +0,0 @@
-import path from 'node:path';
-
-import { buildDesignIntentSeedFromSignals } from '../../project-scaffolder.mjs';
-
-export function buildUpgradeDesignIntentSeed({
-  targetDirectoryPath,
-  packageManifest,
-  selectedStackFileName,
-  selectedBlueprintFileName,
-  uiScopeSignals,
-}) {
-  const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim()
-    || 'existing-ui-project';
-  const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
-    || String(selectedStackFileName || '').toLowerCase().includes('flutter')
-    || uiScopeSignals.signalReasons.some((signalReason) => {
-      return signalReason.includes('android') || signalReason.includes('ios');
-    });
-  const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
-  const projectDescription = String(packageManifest?.description || '').trim()
-    || `Existing ${resolvedDomain.toLowerCase()} detected during upgrade. Create a project-specific dynamic design contract before shipping new UI work.`;
-
-  return buildDesignIntentSeedFromSignals({
-    projectName,
-    projectDescription,
-    primaryDomain: resolvedDomain,
-    features: [],
-    initContext: {
-      stackFileName: selectedStackFileName,
-      blueprintFileName: selectedBlueprintFileName,
-    },
-    status: 'seed-generated-during-upgrade',
-    supplementalFields: {
-      upgradeSignals: {
-        detectedFrom: uiScopeSignals.signalReasons,
-        generatedBy: 'upgrade-seed',
-      },
-      repoEvidence: {
-        uiSignalReasons: uiScopeSignals.signalReasons,
-        frontendMetrics: uiScopeSignals.frontendEvidenceMetrics || null,
-        designEvidenceSummary: uiScopeSignals.designEvidenceSummary || null,
-        workspaceUiEntries: uiScopeSignals.workspaceUiEntries || [],
-      },
-    },
-  });
-}

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

@@ -1,190 +0,0 @@
-/**
- * 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',
-  }];
-}
-
-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,
-} = {}) {
-  const metadata = {
-    researchVerifiedAt: null,
-    freshnessWindowDays: FRESHNESS_WINDOW_DAYS,
-    freshnessRule: FRESHNESS_RULE,
-    antiRepeatLedger: {
-      blocklistFromHistory: true,
-      ledgerScope: 'signature-level-descriptors-only',
-      ledgerMaxEntriesPerCategory: 3,
-      previousAnchors: [],
-      previousPalettes: [],
-      previousMotionSignatures: [],
-      previousTypographyChoices: [],
-      previousStructuralFingerprints: [],
-    },
-    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);
-    metadata.antiRepeatLedger.previousTypographyChoices = buildPreviousTypographyEntry(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' };
-}