@ryuenn3123/agentic-senior-core 3.0.16 → 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 [
@@ -133,9 +131,10 @@ export function buildDesignBootstrapPrompt({
     '8. Responsive Strategy and Cross-Viewport Adaptation Matrix',
     '9. Motion and Interaction Principles',
     '10. Component Language and Morphology (cards, forms, nav, states)',
-    '11. Accessibility Non-Negotiables',
-    '12. Anti-Patterns to Avoid',
-    '13. Implementation Notes for Future UI Tasks',
+    '11. Context Hygiene and Approved Reference Boundaries',
+    '12. Accessibility Non-Negotiables',
+    '13. Anti-Patterns to Avoid',
+    '14. Implementation Notes for Future UI Tasks',
     '',
     '## Required design-intent.json Fields',
     '1. mode',
@@ -151,11 +150,17 @@ export function buildDesignBootstrapPrompt({
     '11. crossViewportAdaptation',
     '12. motionSystem',
     '13. componentMorphology',
-    '14. experiencePrinciples',
-    '15. forbiddenPatterns',
-    '16. validationHints',
-    '17. requiredDesignSections',
-    '18. implementation',
+    '14. accessibilityPolicy',
+    '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.',
@@ -169,8 +174,19 @@ export function buildDesignBootstrapPrompt({
     '9. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
     '10. Motion can be bold, cinematic, or highly expressive when it improves memorability, hierarchy, feedback, or product confidence. Optimize it instead of flattening it. Only reject motion when it harms clarity, accessibility, or runtime performance.',
     '11. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
-    '11. 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.',
-    '12. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '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. 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}`,
@@ -181,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(),
     '```',
@@ -189,8 +205,15 @@ export function buildDesignBootstrapPrompt({
     '## Required Execution',
     '1. Create or update docs/DESIGN.md with complete content.',
     '2. Create or update docs/design-intent.json with machine-readable design intent.',
-    '3. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
-    '4. After the contract exists, use it as a first-class source for future UI tasks.',
+    '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 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.16",
+  "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/documentation-boundary-audit.mjs

@@ -53,7 +53,10 @@ const BOUNDARY_RULES = [
     ],
     trigger(filePath) {
       return !isDocumentationFilePath(filePath)
-        && /(api|openapi|contract|controller|route|endpoint)/i.test(filePath);
+        && (
+          /(api|openapi|controller|route|endpoint)/i.test(filePath)
+          || /api[-_/]?contract/i.test(filePath)
+        );
     },
     docsMatcher(filePath) {
       return filePath === '.agent-context/rules/api-docs.md'
@@ -285,4 +288,4 @@ function runDocumentationBoundaryAudit() {
   process.exit(reportPayload.passed ? 0 : 1);
 }
 
-runDocumentationBoundaryAudit();
+runDocumentationBoundaryAudit();

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',
@@ -54,6 +57,14 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'UI scope trigger signals',
   'visual intent, interaction quality, and conversion clarity',
   'template-only repetitive outputs',
+  'Context Hygiene and Reference Boundaries (Mandatory)',
+  'Accessibility Split (Mandatory)',
+  'Design continuity is opt-in.',
+  'repo evidence wins',
+  'WCAG 2.2 AA as the hard compliance floor',
+  'APCA as an advisory readability model',
+  '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.',
@@ -69,6 +80,16 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'crossViewportAdaptation.mutationRules.mobile/tablet/desktop',
   'motionSystem',
   'componentMorphology',
+  'accessibilityPolicy',
+  'designExecutionPolicy',
+  'designExecutionHandoff',
+  'reviewRubric',
+  'contextHygiene',
+  'Design continuity is opt-in.',
+  'WCAG 2.2 AA as the blocking baseline',
+  'APCA only as advisory perceptual tuning',
+  'Structured design execution must stay representation-first',
+  'structured handoff',
 ];
 
 const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
@@ -77,6 +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.',
+  'Structured design execution summary was supplied to semantic review.',
+  'designExecutionSignalCount',
+  'designExecutionPolicy',
+  'designExecutionHandoff',
+  'reviewRubric',
+  'genericityStatus',
+  'handoffReady',
+  'calibratedStatus',
 ];
 
 const REQUIRED_INSTRUCTIONS_SNIPPETS = [
@@ -84,6 +113,11 @@ const REQUIRED_INSTRUCTIONS_SNIPPETS = [
   'bootstrap-design.md',
   'frontend-architecture.md',
   'do not eagerly load unrelated backend-only rules',
+  'valid style context',
+  'explicitly approved reference systems',
+  'WCAG 2.2 AA as the hard compliance floor',
+  'APCA as advisory perceptual tuning only',
+  '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;
+}