@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.19

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -98,12 +98,10 @@ export function buildDesignBootstrapPrompt({
   discoveryAnswers,
   initContext,
   docsLanguage,
-  architectureRecommendation,
 }) {
   const designIntentSeed = buildDesignIntentSeed({
     discoveryAnswers,
     initContext,
-    architectureRecommendation,
   });
 
   return [
@@ -153,14 +151,16 @@ export function buildDesignBootstrapPrompt({
     '12. motionSystem',
     '13. componentMorphology',
     '14. accessibilityPolicy',
-    '15. visualQaPolicy',
-    '16. contextHygiene',
-    '17. experiencePrinciples',
-    '18. forbiddenPatterns',
-    '19. validationHints',
-    '20. requiredDesignSections',
-    '21. implementation',
-    '22. repoEvidence when onboarding or detector evidence exists',
+    '15. designExecutionPolicy',
+    '16. designExecutionHandoff',
+    '17. reviewRubric',
+    '18. contextHygiene',
+    '19. experiencePrinciples',
+    '20. forbiddenPatterns',
+    '21. validationHints',
+    '22. requiredDesignSections',
+    '23. implementation',
+    '24. repoEvidence when onboarding or detector evidence exists',
     '',
     '## Hard Rules',
     '1. No copy-paste from external style guides.',
@@ -177,12 +177,16 @@ export function buildDesignBootstrapPrompt({
     '12. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only rules unless the task explicitly crosses those boundaries.',
     '13. Treat WCAG 2.2 AA as the hard accessibility floor. Use APCA only as advisory perceptual tuning, never as a reason to waive a WCAG failure.',
     '14. Accessibility planning must explicitly cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
-    '15. Hybrid visual QA must stay deterministic-first. Define screenshot-baseline expectations, dynamic masking rules, noise thresholds, required mobile/tablet/desktop coverage, and long-page capture strategy before relying on semantic review.',
-    '16. Do not treat one screenshot as enough for a long page. Require above-fold capture, full-page capture when stable, and anchor-based section or tiled-scroll captures for deep pages.',
-    '17. Only escalate visual diffs to a semantic judge when deterministic evidence shows meaningful drift or missing required coverage.',
-    '18. Treat prior website memory, unrelated project aesthetics, and remembered screenshots as tainted context unless the user explicitly approves continuity.',
-    '19. Design continuity is opt-in. If no approved continuity exists, synthesize from the current repo evidence, current brief, and current project docs only.',
-    '20. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '15. Structured design execution must stay representation-first. Define a surface plan, component graph, content-priority map, viewport mutation plan, and interaction-state matrix before relying on semantic review.',
+    '16. design-intent.json must carry an explicit structured handoff, not just policy flags. The handoff should make surface plans, component relationships, task flow, and signature moves executable before coding starts.',
+    '17. Do not depend on screenshot capture, browser automation, or image diff artifacts as the default path. The contract must be strong enough to guide precise UI from repo evidence, component logic, and user intent alone.',
+    '18. Semantic review should judge contract fidelity, distinctiveness, hierarchy, state behavior, and viewport mutation directly from the contract and changed UI code.',
+    '19. Treat prior website memory, unrelated project aesthetics, and remembered screenshots as tainted context unless the user explicitly approves continuity.',
+    '20. Design continuity is opt-in. If no approved continuity exists, synthesize from the current repo evidence, current brief, and current project docs only.',
+    '21. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '22. Define a stable review rubric for distinctiveness, contract fidelity, visual consistency, heuristic UX quality, and motion discipline.',
+    '23. Genericity findings must name the actual drift signal. Do not label something generic without explaining the anti-pattern or rubric dimension.',
+    '24. Separate taste from failure. Bold direction is allowed when it still follows the contract, serves the product, and stays accessible.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -193,7 +197,7 @@ export function buildDesignBootstrapPrompt({
     `- Blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
     '',
     '## Seed Machine Contract',
-    'Refine this seed instead of discarding it. Keep the final JSON aligned with the markdown design system.',
+    'Refine this scaffold seed instead of discarding it. Keep the structural fields that are already valid, but replace placeholder expressive direction with project-specific reasoning grounded in repo evidence and the active brief.',
     '```json',
     designIntentSeed.trim(),
     '```',
@@ -203,11 +207,13 @@ export function buildDesignBootstrapPrompt({
     '2. Create or update docs/design-intent.json with machine-readable design intent.',
     '3. Keep both files synchronized: the markdown explains the rationale and the JSON captures the machine-readable contract.',
     '4. Encode accessibility as a split policy: WCAG 2.2 AA hard floor, APCA advisory readability tuning, and explicit hard-vs-advisory checks.',
-    '5. Encode hybrid visual QA as policy: deterministic-first screenshot review, approved masking categories, stability thresholds, required mobile/tablet/desktop coverage, long-page capture strategy, and semantic escalation boundaries.',
-    '6. Make long-page handling explicit: above-fold capture, full-page capture when stable, and anchor-based section or tiled-scroll captures when one image would miss deep content.',
-    '7. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists instead of discarding it.',
-    '8. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
-    '9. After the contract exists, use it as a first-class source for future UI tasks.',
+    '5. Encode structured design execution as policy: representation strategy, surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, semantic review focus, and structured handoff requirements.',
+    '6. Encode an explicit structured handoff inside docs/design-intent.json: surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, task-flow narrative, and signature move rationale.',
+    '7. Encode a stable review rubric: required dimensions, genericity signals, valid bold signals, and reporting rules that separate taste from real failure.',
+    '8. Make the handoff executable without screenshot dependency. The contract should still guide high-precision UI generation from repo evidence and changed code alone.',
+    '9. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists instead of discarding it.',
+    '10. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
+    '11. After the contract exists, use it as a first-class source for future UI tasks.',
     '',
   ].join('\n');
 }

package/lib/cli/project-scaffolder/storage.mjs

@@ -66,7 +66,6 @@ export async function generateProjectDocumentation(
       discoveryAnswers,
       initContext: synthesisContext,
       docsLanguage: normalizedDocsLanguage,
-      architectureRecommendation,
     });
     await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
     generatedPromptFileNames.push(designPromptFileName);
@@ -75,7 +74,6 @@ export async function generateProjectDocumentation(
     const designIntentSeedContent = buildDesignIntentSeed({
       discoveryAnswers,
       initContext: synthesisContext,
-      architectureRecommendation,
     });
     await fs.writeFile(path.join(docsDirectoryPath, designIntentSeedFileName), designIntentSeedContent, 'utf8');
     materializedFileNames.push(designIntentSeedFileName);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.17",
+  "version": "3.0.19",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -66,6 +66,6 @@
     "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "validate": "node ./scripts/validate.mjs",
-    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/enterprise-ops.test.mjs"
+    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/enterprise-ops.test.mjs"
   }
 }

package/scripts/frontend-usability-audit.mjs

@@ -23,6 +23,9 @@ const REQUIRED_FILES = [
   '.instructions.md',
   '.agent-context/prompts/bootstrap-design.md',
   'scripts/ui-design-judge.mjs',
+  'scripts/ui-rubric-calibration.mjs',
+  'scripts/ui-design-judge/rubric-calibration.mjs',
+  'scripts/ui-design-judge/rubric-goldset.json',
   '.agent-context/rules/frontend-architecture.md',
   '.agent-context/review-checklists/pr-checklist.md',
   '.agent-context/review-checklists/architecture-review.md',
@@ -60,8 +63,8 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'repo evidence wins',
   'WCAG 2.2 AA as the hard compliance floor',
   'APCA as an advisory readability model',
-  'Hybrid Visual QA Boundaries (Mandatory)',
-  'Visual QA must be deterministic-first.',
+  'Structured Design Execution Boundaries (Mandatory)',
+  'UI review must stay representation-first.',
   'UI Consistency Guardrails (Mandatory)',
   'Content language must stay consistent per screen and flow unless user requests multilingual output.',
   'Text color must remain contrast-safe against its background; no color collisions.',
@@ -78,12 +81,15 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'motionSystem',
   'componentMorphology',
   'accessibilityPolicy',
-  'visualQaPolicy',
+  'designExecutionPolicy',
+  'designExecutionHandoff',
+  'reviewRubric',
   'contextHygiene',
   'Design continuity is opt-in.',
   'WCAG 2.2 AA as the blocking baseline',
   'APCA only as advisory perceptual tuning',
-  'Hybrid visual QA must stay deterministic-first',
+  'Structured design execution must stay representation-first',
+  'structured handoff',
 ];
 
 const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
@@ -92,9 +98,14 @@ const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
   'Runs only in advisory mode for this repository workflow.',
   'Do not reward generic SaaS defaults or popular template patterns.',
   'UI design judge only evaluates changed UI surfaces.',
-  'Deterministic visual diff reported no meaningful drift, so semantic review was skipped.',
-  'UI_VISUAL_DIFF_REPORT_JSON',
-  'meaningfulDiffViewportCount',
+  'Structured design execution summary was supplied to semantic review.',
+  'designExecutionSignalCount',
+  'designExecutionPolicy',
+  'designExecutionHandoff',
+  'reviewRubric',
+  'genericityStatus',
+  'handoffReady',
+  'calibratedStatus',
 ];
 
 const REQUIRED_INSTRUCTIONS_SNIPPETS = [
@@ -106,7 +117,7 @@ const REQUIRED_INSTRUCTIONS_SNIPPETS = [
   'explicitly approved reference systems',
   'WCAG 2.2 AA as the hard compliance floor',
   'APCA as advisory perceptual tuning only',
-  'deterministic screenshot or diff evidence as the first layer',
+  'Do not require screenshot capture as a baseline dependency',
 ];
 
 const REQUIRED_DESIGN_EVIDENCE_SNIPPETS = [

package/scripts/mcp-server/constants.mjs

@@ -0,0 +1,60 @@
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+export const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..', '..');
+export const STATE_DIRECTORY = resolve(REPOSITORY_ROOT, '.agent-context', 'state');
+export const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
+export const DEFAULT_FETCH_TIMEOUT_MS = 15000;
+export const DEFAULT_FETCH_MAX_CHARS = 6000;
+export const MAX_FETCH_MAX_CHARS = 20000;
+export const DEFAULT_TREND_WINDOW_DAYS = 90;
+export const MAX_TREND_PACKAGES = 10;
+export const FALLBACK_PACKAGE_VERSION = '0.0.0-local';
+
+function resolvePackageVersion() {
+  try {
+    const parsedPackageManifest = JSON.parse(
+      readFileSync(resolve(REPOSITORY_ROOT, 'package.json'), 'utf8')
+    );
+    const rawVersion = typeof parsedPackageManifest?.version === 'string'
+      ? parsedPackageManifest.version.trim()
+      : '';
+
+    return rawVersion || FALLBACK_PACKAGE_VERSION;
+  } catch {
+    return FALLBACK_PACKAGE_VERSION;
+  }
+}
+
+export const PACKAGE_VERSION = resolvePackageVersion();
+
+export const TEST_SUITE_ARGS = {
+  full: ['--test', './tests/cli-smoke.test.mjs', './tests/mcp-server.test.mjs', './tests/llm-judge.test.mjs', './tests/enterprise-ops.test.mjs'],
+  cli: ['--test', './tests/cli-smoke.test.mjs'],
+  enterprise: ['--test', './tests/enterprise-ops.test.mjs'],
+  'llm-judge': ['--test', './tests/llm-judge.test.mjs'],
+};
+
+export const INTERNAL_SCRIPT_PATHS = {
+  validate: resolve(REPOSITORY_ROOT, 'scripts', 'validate.mjs'),
+  release_gate: resolve(REPOSITORY_ROOT, 'scripts', 'release-gate.mjs'),
+  forbidden_content_check: resolve(REPOSITORY_ROOT, 'scripts', 'forbidden-content-check.mjs'),
+};
+
+function getAvailableTestSuites() {
+  return Object.entries(TEST_SUITE_ARGS)
+    .filter(([, commandArguments]) => (
+      Array.isArray(commandArguments)
+      && commandArguments.length > 1
+      && commandArguments
+        .slice(1)
+        .every((relativeTestPath) => existsSync(resolve(REPOSITORY_ROOT, relativeTestPath)))
+    ))
+    .map(([suiteName]) => suiteName);
+}
+
+export const AVAILABLE_TEST_SUITES = getAvailableTestSuites();

package/scripts/mcp-server/tool-registry.mjs

@@ -0,0 +1,149 @@
+// @ts-check
+
+import { existsSync } from 'node:fs';
+import { AVAILABLE_TEST_SUITES, INTERNAL_SCRIPT_PATHS } from './constants.mjs';
+
+export function buildToolDefinitions() {
+  const toolDefinitions = [];
+
+  if (existsSync(INTERNAL_SCRIPT_PATHS.validate)) {
+    toolDefinitions.push({
+      name: 'validate',
+      description: 'Run repository validation checks.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    });
+  }
+
+  if (AVAILABLE_TEST_SUITES.length > 0) {
+    toolDefinitions.push({
+      name: 'test',
+      description: 'Run test suites (full or targeted).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          suite: {
+            type: 'string',
+            enum: AVAILABLE_TEST_SUITES,
+            description: 'Target test suite. Defaults to the first available suite.',
+          },
+        },
+        additionalProperties: false,
+      },
+    });
+  }
+
+  if (existsSync(INTERNAL_SCRIPT_PATHS.release_gate)) {
+    toolDefinitions.push({
+      name: 'release_gate',
+      description: 'Run release gate checks.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    });
+  }
+
+  if (existsSync(INTERNAL_SCRIPT_PATHS.forbidden_content_check)) {
+    toolDefinitions.push({
+      name: 'forbidden_content_check',
+      description: 'Run forbidden content scan used by publish gate.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    });
+  }
+
+  toolDefinitions.push(
+    {
+      name: 'research_fetch',
+      description: 'Fetch external documentation/news content and return query-focused excerpts with citation metadata.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          url: {
+            type: 'string',
+            description: 'Absolute HTTP/HTTPS URL to fetch.',
+          },
+          query: {
+            type: 'string',
+            description: 'Optional search query used to extract focused excerpts.',
+          },
+          maxChars: {
+            type: 'integer',
+            description: 'Maximum characters to return when query is not provided (default 6000, max 20000).',
+          },
+        },
+        required: ['url'],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: 'trend_snapshot',
+      description: 'Generate ecosystem trend snapshot from npm registry metadata with source timestamps.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          packages: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Package names to inspect (max 10).',
+          },
+          windowDays: {
+            type: 'integer',
+            description: 'Release activity window in days (default 90).',
+          },
+        },
+        required: ['packages'],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: 'state_read',
+      description: 'Read a file from .agent-context/state for cross-session continuity.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Path relative to .agent-context/state (for example memory-continuity-benchmark.json).',
+          },
+        },
+        required: ['path'],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: 'state_write',
+      description: 'Write a file under .agent-context/state for cross-session continuity updates.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Path relative to .agent-context/state.',
+          },
+          content: {
+            type: 'string',
+            description: 'UTF-8 content to write.',
+          },
+          mode: {
+            type: 'string',
+            enum: ['overwrite', 'append'],
+            description: 'Write mode. Defaults to overwrite.',
+          },
+        },
+        required: ['path', 'content'],
+        additionalProperties: false,
+      },
+    },
+  );
+
+  return toolDefinitions;
+}