@ryuenn3123/agentic-senior-core 4.2.5 → 4.2.7

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

@@ -4,6 +4,16 @@ Use this prompt for UI, UX, frontend layout, screen, Tailwind, animation, 3D, ca
 Create or refine `docs/DESIGN.md` for human reasoning and `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
 
 This contract is a decision scaffold, not a style preset. We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
+
+## MANDATORY FIRST STEP
+
+Check `docs/design-intent.json`:
+- If `status` contains "seed" OR `researchDossier.metadata.researchVerifiedAt` is null → STOP.
+- Do NOT write UI code.
+- Do NOT fill `conceptualAnchor`, color tokens, typography tokens, or motion tokens with concrete values.
+- **Existing UI exception**: If the project already has a mature UI and the user only asked for an additive feature (not a redesign), you may skip Sections 3-5 of `research-design.md`. Instead, document the existing direction as the `conceptualAnchor`, set token classifications to `continuity-retained`, set `status` to `active`, set `researchVerifiedAt` to today's date, and proceed.
+- Otherwise, run `research-design.md` Sections 3, 4, and 5 first. All three must produce filled artifacts before proceeding.
+- The scaffold file is a structure only. Filling placeholders without completing research is a violation of this contract.
 ## Authority
 - Treat `.agent-context/` and current project docs as technical authority.
 - Treat `README.md` as public and developer overview, setup, usage, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
@@ -23,13 +33,40 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 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`.
 10. Complete the Live Source Freshness Gate from `research-design.md` before claiming that a visual pattern, library, browser feature, accessibility requirement, or interaction style is current. Record `sourceFreshness` and `evidenceTable[]` in `docs/design-intent.json`.
+## Internal Vocabulary Rule
+
+The following terms are internal process labels only. 
+They must NEVER appear in:
+- UI copy or component text
+- Public-facing documentation
+- Section headings in DESIGN.md
+- Any text the user reads in the product
+
+Forbidden in output: evidence, dossier, anchor, category-code, 
+morphological, rename test, freshness gate, ledger, accession, 
+provenance, custody, specimen, taxonomy, invariant.
+
+Translate all decisions into plain product language before writing 
+them into DESIGN.md or any UI-facing artifact.
+
+Good: "Typography uses a serif display font paired with monospace for 
+code blocks, creating clear hierarchy between narrative and technical content."
+
+Bad: "The anchor-derived typographic decision pairs a display serif 
+with strict mono per the morphological exploration output."
+
 ## 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
 - one signature motion behavior more specific than "smooth"
 - one typographic decision with meaningful role contrast
 - one authored visual bet visible in the first viewport
-Reject generic anchors. Do not accept "modern", "clean", "premium", "expressive", "minimal", or "bold" as the anchor. Name a material, instrument, artifact class, architectural system, editorial genre, cinematic behavior, exhibition system, scientific apparatus, or industrial mechanism.
+Reject generic anchors. Do not accept "modern", "clean", "premium", "expressive", "minimal", or "bold" as the anchor. Name a specific real-world reference. Valid options include:
+- A specific premium digital experience (e.g., "[Specific Brand] hardware launch page full-bleed section transitions", "[Specific Tool] homepage keyboard-first density rhythm", "[Specific Fintech] marketing site gradient mesh motion")
+- A cinematic campaign or editorial system
+- A material, instrument, or physical mechanism
+
+The reference must be googleable and specific. "Brand-X-style" fails. "[Brand X] M3 reveal page scroll-locked section reveals" passes.
 ## Dynamic Avant-Garde Anchor Engine
 If no current-task research or visual reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding.
 Rules:

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

@@ -69,6 +69,47 @@ Before any visual choice, write a structured product reading:
 
 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.
 
+## Reference Routing
+
+After Section 1, identify the product category. Then run web_search 
+and web_fetch on the matching domains below (or other modern, highly-regarded digital product equivalents) before picking any anchor.
+
+Developer tool / CLI / AI infrastructure:
+→ Linear, Raycast, Vercel, Warp, Resend, Railway (or equivalents)
+
+SaaS / B2B productivity:
+→ Notion, Loom, Cron, Superhuman, Intercom (or equivalents)
+
+AI product / API:
+→ Anthropic, Perplexity, ElevenLabs, Replicate, Mistral (or equivalents)
+
+Ecommerce:
+→ SSENSE, Allbirds, Represent, Shopify examples (or equivalents)
+
+Design tool / creative:
+→ Framer, Spline, Rive, Penpot (or equivalents)
+
+Consumer / mobile:
+→ Arc browser, Craft, Things, Bear (or equivalents)
+
+Data / analytics:
+→ Retool, Posthog, Metabase, Grafana (or equivalents)
+
+For every product category:
+→ Also check: Awwwards, Godly.website, and Layers.to for 
+  state-of-the-art quality references in that category.
+
+DO NOT fetch: Wikipedia, Dribbble templates, or generic blog posts 
+about "best UI design practices."
+
+For each reference: fetch the actual 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.
@@ -163,6 +204,7 @@ From the selected morphological combination, generate exactly five anchor candid
 
 Hard constraints on anchors:
 - The anchor must be concrete and googleable. "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. Be specific enough that the reference fails the rename test.
 - Do not default to spatial place metaphors such as room, darkroom, control room, counting room, war room, studio, lab, cockpit, command center. Use them only when the product genuinely depends on a physical place model. Prefer artifacts, custody flows, instruments, data behaviors, materials, editorial systems, service rituals, or interaction mechanisms.
 - Pass the strengthened rename test: mentally rename the product to three genuinely different categories. 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).
 

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

@@ -32,7 +32,7 @@ export function buildConceptualAnchorSection() {
       doNotRevealHiddenCandidateList: true,
       outputOnlyChosenAnchor: true,
       avoidSpatialPlaceMetaphorByDefault: true,
-      preferMechanismOverPlace: true,
+      preferSpecificOverGeneric: true,
     },
     creativeCommitmentPolicy: {
       requiredBeforeComplianceReview: true,
@@ -63,13 +63,14 @@ export function buildConceptualAnchorSection() {
       'command-center',
     ],
     sourceDomains: [
-      'complex-physical-engineering',
+      'premium-interactive-web-experiences',
+      'cinematic-campaign-and-product-launch', 
+      'contemporary-editorial-digital-design',
       'cinematic-behavior-and-transition-systems',
       'experimental-editorial-structure',
-      'scientific-instrumentation',
-      'workflow-and-custody-systems',
+      'complex-physical-engineering',
       'material-artifacts-and-instruments',
-      'premium-interactive-web-experiences',
+      'workflow-and-custody-systems',
     ],
     visualRiskBudget: {
       mode: 'high-distinctiveness-with-accessibility-and-performance-guardrails',

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

@@ -1,3 +1,4 @@
+// @file-size-exception: Structural validation gates expanded size
 /**
  * Design Intent Contract builder. Composes the structured contract from
  * focused section builders living under `design-contract/`. Public exports
@@ -57,6 +58,18 @@ function buildDesignIntentContractObject({
   });
 
   return {
+    _gate: {
+      phase: 'scaffold-only',
+      instruction: 'DO NOT fill conceptualAnchor, derivedTokenLogic, or any token values until research-design.md Sections 3, 4, and 5 are complete. Do not simplify or rewrite this scaffold. Fill fields in-place after research.',
+      blockedFields: [
+        'conceptualAnchor.anchorReference',
+        'conceptualAnchor.categoryCodes.candidateEntries',
+        'conceptualAnchor.morphologicalExploration.selectedCombination',
+        'conceptualAnchor.anchorCandidates.candidates',
+        'derivedTokenLogic.colorDerivationSource',
+        'motionPaletteDecision'
+      ]
+    },
     mode: 'dynamic',
     status,
     seedPolicy: {
@@ -408,6 +421,10 @@ export function buildDesignIntentSeed({
  */
 export const __DESIGN_CONTRACT_SCHEMA_INDEX__ = Object.freeze([
   // top-level structural fields
+  '_gate',
+  'phase',
+  'instruction',
+  'blockedFields',
   'tokenSystem',
   'seedPolicy',
   'structure-first-scaffold',

package/package.json

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

package/scripts/validate/coverage-checks.mjs

@@ -355,7 +355,7 @@ export async function validateInstructionAdapters(context) {
   ];
   const instructionFootprintLimits = [
     { path: 'AGENTS.md', maxLines: 180 },
-    { path: '.agent-context/prompts/bootstrap-design.md', maxLines: 180 },
+    { path: '.agent-context/prompts/bootstrap-design.md', maxLines: 220 },
     { path: '.agent-context/rules/frontend-architecture.md', maxLines: 180 },
   ];