@ryuenn3123/agentic-senior-core 3.0.10 → 3.0.12

package/lib/cli/project-scaffolder.mjs

@@ -315,7 +315,7 @@ const DESIGN_REQUIRED_SECTIONS = [
   'Spacing, Layout Rhythm, and Density Strategy',
   'Responsive Strategy and Cross-Viewport Adaptation Matrix',
   'Interaction, Motion, and Feedback Rules',
-  'Component Language and Shared Patterns',
+  'Component Language, Morphology, and Shared Patterns',
   'Accessibility Non-Negotiables',
   'Anti-Patterns to Avoid',
   'Implementation Notes for Future UI Tasks',
@@ -343,6 +343,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Keep decision-critical information prominent while secondary merchandising stays quiet.',
         'Let imagery and spacing create premium perception before decorative effects do.',
       ],
+      motionPurpose: 'Use restrained motion to reinforce buying confidence, product continuity, and feedback. Motion should feel premium, not promotional.',
+      motionChoreography: 'Favor short hover/focus transitions, sheet choreography, and product-media continuity. Avoid looping hero motion, autoplay spectacle, and parallax-heavy scenes.',
+      motionDurations: {
+        desktop: 180,
+        mobile: 240,
+      },
+      componentMorphology: {
+        mobile: 'Product cards should compress supporting metadata, pin purchase actions closer to the thumb zone, and move comparison into progressive disclosure or bottom sheets.',
+        tablet: 'Cards and merch modules should preserve comparison affordances while reducing tertiary chrome and keeping visual hierarchy stable.',
+        desktop: 'Cards can expand media, comparison, and reassurance copy while keeping buying cues dominant and visually disciplined.',
+      },
       mutationRules: {
         mobile: 'Convert browsing into vertically stacked product cards, move cart and filter actions into sticky or bottom-sheet patterns, and keep thumb-reach actions persistent.',
         tablet: 'Preserve browsing flow with a two-column rhythm, collapse tertiary filters, and keep comparison moments visible without forcing desktop density.',
@@ -365,6 +376,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use visual weight to separate signal from operational noise.',
         'Reserve strong accents for alerts, decisions, and state transitions only.',
       ],
+      motionPurpose: 'Use motion as operational feedback and state continuity, never as ambient decoration that competes with dense information.',
+      motionChoreography: 'Prefer fast transitions for filters, drawers, status reveals, and row expansion. Avoid floaty choreography and ornamental motion that slows scanning.',
+      motionDurations: {
+        desktop: 160,
+        mobile: 220,
+      },
+      componentMorphology: {
+        mobile: 'Data rows should become prioritized cards or grouped summaries, with filters and secondary tools moving into sheets or drawers.',
+        tablet: 'Operational panels should retain split-view logic where possible, while tertiary panels collapse behind explicit toggles.',
+        desktop: 'Dense tables, side panels, and comparison surfaces can remain visible simultaneously, with state treatments optimized for rapid scanning.',
+      },
       mutationRules: {
         mobile: 'Collapse dense tables into prioritized cards or row groups, move filters into drawers or sheets, and pin the most critical actions to the bottom reach zone.',
         tablet: 'Keep two-column or split-pane workflows, collapse tertiary panels, and maintain fast scan paths for operators using touch or keyboard.',
@@ -387,6 +409,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use code-adjacent rhythm and hierarchy to build trust with technical users.',
         'Keep complexity legible through spacing, grouping, and explicit interaction states.',
       ],
+      motionPurpose: 'Use motion to clarify causality, reveal system state, and preserve context during multi-pane technical workflows.',
+      motionChoreography: 'Prefer subtle panel transitions, command feedback, and disclosure motion. Avoid ornamental sweeps that make technical work feel imprecise.',
+      motionDurations: {
+        desktop: 170,
+        mobile: 230,
+      },
+      componentMorphology: {
+        mobile: 'Technical panes should flatten into sequential sections, with commands and diagnostics colocated near the content they affect.',
+        tablet: 'Split views should survive where useful, with explicit panel toggles and condensed chrome for code-adjacent tasks.',
+        desktop: 'Navigation, documentation, diagnostics, and active work surfaces can remain concurrently visible when it improves expert comprehension.',
+      },
       mutationRules: {
         mobile: 'Switch multi-pane technical layouts into stacked sections, turn secondary navigation into segmented or sheet-based controls, and keep commands near the content they affect.',
         tablet: 'Retain split-view comprehension where possible, compress chrome, and keep documentation or diagnostics adjacent to the active task.',
@@ -409,6 +442,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use contrast and spacing to guide attention between creation, moderation, and discovery.',
         'Give key interaction moments personality without sacrificing clarity.',
       ],
+      motionPurpose: 'Use motion to support reading rhythm, reveal structure, and reward contribution moments without overwhelming long-form consumption.',
+      motionChoreography: 'Favor reveal choreography for section transitions, lightweight feedback on participation, and measured media behavior. Avoid constant background motion.',
+      motionDurations: {
+        desktop: 190,
+        mobile: 250,
+      },
+      componentMorphology: {
+        mobile: 'Reading surfaces should dominate while secondary discovery and community tools collapse behind sheets, tabs, or segmented controls.',
+        tablet: 'Editorial modules can balance reading and discovery, provided the primary narrative flow remains obvious.',
+        desktop: 'Long-form content, secondary navigation, and related discovery modules can coexist without fragmenting the reading rhythm.',
+      },
       mutationRules: {
         mobile: 'Prioritize reading and contribution flows in a single-column narrative stack, tuck secondary discovery tools behind sheets, and keep primary creation actions within reach.',
         tablet: 'Balance narrative reading with supporting discovery modules, using two-column compositions only where hierarchy stays obvious.',
@@ -430,6 +474,17 @@ function inferDesignKeywords(discoveryAnswers) {
       'Use rhythm, hierarchy, and motion intentionally so the interface feels authored.',
       'Keep the system flexible enough to evolve with product scope without losing identity.',
     ],
+    motionPurpose: 'Allow motion when it improves continuity, feedback, or perceived craft. Avoid banning motion outright, but reject decorative movement with no product value.',
+    motionChoreography: 'Use short, purposeful transitions and keep heavier choreography rare, opt-in, and explainable in product terms.',
+    motionDurations: {
+      desktop: 180,
+      mobile: 240,
+    },
+    componentMorphology: {
+      mobile: 'Primary components should simplify structure, prioritize direct tasks, and collapse supporting detail into explicit disclosure.',
+      tablet: 'Components should preserve hierarchy and task continuity while reducing density and compressing tertiary chrome.',
+      desktop: 'Components can expose richer states, denser supporting information, and broader navigation affordances without losing clarity.',
+    },
     mutationRules: {
       mobile: 'Stack primary tasks vertically, convert secondary navigation into thumb-friendly overlays or sheets, and simplify dense comparison layouts into progressive disclosure.',
       tablet: 'Preserve hierarchy with fewer columns, condensed chrome, and adaptive navigation that maintains task continuity.',
@@ -491,11 +546,28 @@ function buildDesignIntentContractObject({
       touchTargetMinPx: 44,
       mutationRules: inferredKeywords.mutationRules,
     },
+    motionSystem: {
+      allowMeaningfulMotion: true,
+      purpose: inferredKeywords.motionPurpose,
+      choreography: inferredKeywords.motionChoreography,
+      desktopDurationMs: inferredKeywords.motionDurations.desktop,
+      mobileDurationMs: inferredKeywords.motionDurations.mobile,
+      respectReducedMotion: true,
+      preferTransformAndOpacity: true,
+      avoidDecorativeMotionForItsOwnSake: true,
+    },
+    componentMorphology: {
+      requireStateBehaviorMatrix: true,
+      preserveIdentityAcrossViewports: true,
+      stateKeys: ['default', 'hover', 'focus', 'active', 'disabled', 'loading', 'error'],
+      viewportBehavior: inferredKeywords.componentMorphology,
+    },
     experiencePrinciples: [
       'Design must feel project-specific, not interchangeable with generic SaaS templates.',
       'Major interface decisions must be explainable in product and user terms.',
       'Accessibility, responsiveness, and implementation realism are non-negotiable.',
       'Cross-viewport behavior must reorganize tasks and navigation, not just scale the desktop layout down.',
+      'Motion may add character and continuity when it improves the product experience, but it must stay purposeful, performant, and optional for reduced-motion users.',
     ],
     forbiddenPatterns: [
       'generic-saas-hero',
@@ -509,6 +581,8 @@ function buildDesignIntentContractObject({
       requireViewportMutationRules: true,
       requirePerceptualColorRationale: true,
       allowHexDerivatives: true,
+      requireMotionRationale: true,
+      requireStateMorphology: true,
     },
     requiredDesignSections: DESIGN_REQUIRED_SECTIONS,
     implementation: {
@@ -517,6 +591,7 @@ function buildDesignIntentContractObject({
       requireDistinctVisualDirection: true,
       requireMachineReadableContract: true,
       requireViewportMutationRules: true,
+      requirePurposefulMotionGuidelines: true,
       bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
       autoLoadedRuleFiles: [
         '.agent-context/prompts/bootstrap-design.md',
@@ -589,6 +664,41 @@ export function validateDesignIntentContract(designIntentContract) {
     }
   }
 
+  if (!designIntentContract.motionSystem || typeof designIntentContract.motionSystem !== 'object') {
+    validationErrors.push('designIntent.motionSystem must exist.');
+  } else {
+    if (designIntentContract.motionSystem.allowMeaningfulMotion !== true) {
+      validationErrors.push('designIntent.motionSystem.allowMeaningfulMotion must equal true.');
+    }
+    if (!String(designIntentContract.motionSystem.purpose || '').trim()) {
+      validationErrors.push('designIntent.motionSystem.purpose must be a non-empty string.');
+    }
+    if (designIntentContract.motionSystem.respectReducedMotion !== true) {
+      validationErrors.push('designIntent.motionSystem.respectReducedMotion must equal true.');
+    }
+  }
+
+  if (!designIntentContract.componentMorphology || typeof designIntentContract.componentMorphology !== 'object') {
+    validationErrors.push('designIntent.componentMorphology must exist.');
+  } else {
+    if (designIntentContract.componentMorphology.requireStateBehaviorMatrix !== true) {
+      validationErrors.push('designIntent.componentMorphology.requireStateBehaviorMatrix must equal true.');
+    }
+    if (!Array.isArray(designIntentContract.componentMorphology.stateKeys) || designIntentContract.componentMorphology.stateKeys.length < 4) {
+      validationErrors.push('designIntent.componentMorphology.stateKeys must contain multiple interaction states.');
+    }
+    const viewportBehavior = designIntentContract.componentMorphology.viewportBehavior;
+    if (!viewportBehavior || typeof viewportBehavior !== 'object') {
+      validationErrors.push('designIntent.componentMorphology.viewportBehavior must exist.');
+    } else {
+      for (const viewportKey of ['mobile', 'tablet', 'desktop']) {
+        if (!String(viewportBehavior[viewportKey] || '').trim()) {
+          validationErrors.push(`designIntent.componentMorphology.viewportBehavior.${viewportKey} must be a non-empty string.`);
+        }
+      }
+    }
+  }
+
   if (!Array.isArray(designIntentContract.requiredDesignSections) || designIntentContract.requiredDesignSections.length !== DESIGN_REQUIRED_SECTIONS.length) {
     validationErrors.push('designIntent.requiredDesignSections must match the required design contract sections.');
   } else {
@@ -764,7 +874,7 @@ function buildDesignBootstrapPrompt({
     '6. Spacing, Layout Rhythm, and Density Strategy',
     '7. Responsive Strategy and Cross-Viewport Adaptation Matrix',
     '8. Motion and Interaction Principles',
-    '9. Component Language (cards, forms, nav, states)',
+    '9. Component Language and Morphology (cards, forms, nav, states)',
     '10. Accessibility Non-Negotiables',
     '11. Anti-Patterns to Avoid',
     '12. Implementation Notes for Future UI Tasks',
@@ -780,11 +890,13 @@ function buildDesignBootstrapPrompt({
     '8. mathSystems',
     '9. colorTruth',
     '10. crossViewportAdaptation',
-    '11. experiencePrinciples',
-    '12. forbiddenPatterns',
-    '13. validationHints',
-    '14. requiredDesignSections',
-    '15. implementation',
+    '11. motionSystem',
+    '12. componentMorphology',
+    '13. experiencePrinciples',
+    '14. forbiddenPatterns',
+    '15. validationHints',
+    '16. requiredDesignSections',
+    '17. implementation',
     '',
     '## Hard Rules',
     '1. No copy-paste from external style guides.',
@@ -795,7 +907,9 @@ function buildDesignBootstrapPrompt({
     '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
     '7. Encode color intent in perceptual terms first. Hex values may exist only as implementation derivatives.',
     '8. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
-    '9. 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.',
+    '9. Motion is allowed when it reinforces feedback, continuity, or hierarchy. Do not remove motion entirely, but reject decorative motion that harms clarity or performance.',
+    '10. 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.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.10",
+  "version": "3.0.12",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -43,7 +43,6 @@
   "scripts": {
     "init": "node ./bin/agentic-senior-core.js init",
     "audit:frontend-usability": "node ./scripts/frontend-usability-audit.mjs",
-    "audit:ui-design-judge": "node ./scripts/ui-design-judge.mjs",
     "audit:documentation-boundary": "node ./scripts/documentation-boundary-audit.mjs",
     "audit:context-triggered": "node ./scripts/context-triggered-audit.mjs",
     "audit:rules-guardian": "node ./scripts/rules-guardian-audit.mjs",

package/scripts/frontend-usability-audit.mjs

@@ -64,11 +64,14 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'Responsive Strategy and Cross-Viewport Adaptation Matrix',
   'colorTruth.format',
   'crossViewportAdaptation.mutationRules.mobile/tablet/desktop',
+  'motionSystem',
+  'componentMorphology',
 ];
 
 const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
   'Advisory-first UI design contract judge.',
-  'Default mode is advisory: findings never block release. Strict mode is opt-in.',
+  'Repo-internal workflow audit; no user-facing runtime modes.',
+  '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.',
 ];

package/scripts/mcp-server.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { dirname, resolve, sep } from 'node:path';
@@ -8,9 +8,6 @@ import { fileURLToPath } from 'node:url';
 
 const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
 const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
-const PACKAGE_VERSION = JSON.parse(
-  readFileSync(resolve(REPOSITORY_ROOT, 'package.json'), 'utf8')
-).version;
 const STATE_DIRECTORY = resolve(REPOSITORY_ROOT, '.agent-context', 'state');
 const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
 const DEFAULT_FETCH_TIMEOUT_MS = 15000;
@@ -18,6 +15,24 @@ const DEFAULT_FETCH_MAX_CHARS = 6000;
 const MAX_FETCH_MAX_CHARS = 20000;
 const DEFAULT_TREND_WINDOW_DAYS = 90;
 const MAX_TREND_PACKAGES = 10;
+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;
+  }
+}
+
+const PACKAGE_VERSION = resolvePackageVersion();
 
 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'],
@@ -26,132 +41,172 @@ const TEST_SUITE_ARGS = {
   'llm-judge': ['--test', './tests/llm-judge.test.mjs'],
 };
 
-const TOOL_DEFINITIONS = [
-  {
-    name: 'validate',
-    description: 'Run repository validation checks.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'test',
-    description: 'Run test suites (full or targeted).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        suite: {
-          type: 'string',
-          enum: ['full', 'cli', 'enterprise', 'llm-judge'],
-          description: 'Target test suite. Defaults to full.',
-        },
+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);
+}
+
+const AVAILABLE_TEST_SUITES = getAvailableTestSuites();
+
+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,
       },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'release_gate',
-    description: 'Run release gate checks.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    name: 'forbidden_content_check',
-    description: 'Run forbidden content scan used by publish gate.',
-    inputSchema: {
-      type: 'object',
-      properties: {},
-      additionalProperties: false,
-    },
-  },
-  {
-    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.',
+    });
+  }
+
+  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.',
+          },
         },
-        maxChars: {
-          type: 'integer',
-          description: 'Maximum characters to return when query is not provided (default 6000, max 20000).',
+        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,
       },
-      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).',
+    {
+      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,
       },
-      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).',
+    {
+      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,
       },
-      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.',
+    {
+      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,
       },
-      required: ['path', 'content'],
-      additionalProperties: false,
     },
-  },
-];
+  );
+
+  return toolDefinitions;
+}
+
+const TOOL_DEFINITIONS = buildToolDefinitions();
 
 let incomingBuffer = Buffer.alloc(0);
 
@@ -539,23 +594,50 @@ function runNodeCommand(commandLabel, commandArguments) {
 
 async function executeToolCall(toolName, toolArguments = {}) {
   if (toolName === 'validate') {
+    if (!existsSync(INTERNAL_SCRIPT_PATHS.validate)) {
+      return buildJsonResult({
+        error: 'validate tool is unavailable because scripts/validate.mjs is missing in this workspace.',
+      }, true);
+    }
+
     return runNodeCommand('validate', ['./scripts/validate.mjs']);
   }
 
   if (toolName === 'test') {
+    if (AVAILABLE_TEST_SUITES.length === 0) {
+      return buildJsonResult({
+        error: 'test tool is unavailable because the managed test suites are not present in this workspace.',
+      }, true);
+    }
+
+    const defaultSuite = AVAILABLE_TEST_SUITES[0];
     const requestedSuite = typeof toolArguments.suite === 'string'
       ? toolArguments.suite
-      : 'full';
+      : defaultSuite;
 
-    const selectedSuite = TEST_SUITE_ARGS[requestedSuite] ? requestedSuite : 'full';
+    const selectedSuite = AVAILABLE_TEST_SUITES.includes(requestedSuite)
+      ? requestedSuite
+      : defaultSuite;
     return runNodeCommand(`test:${selectedSuite}`, TEST_SUITE_ARGS[selectedSuite]);
   }
 
   if (toolName === 'release_gate') {
+    if (!existsSync(INTERNAL_SCRIPT_PATHS.release_gate)) {
+      return buildJsonResult({
+        error: 'release_gate tool is unavailable because scripts/release-gate.mjs is missing in this workspace.',
+      }, true);
+    }
+
     return runNodeCommand('release_gate', ['./scripts/release-gate.mjs']);
   }
 
   if (toolName === 'forbidden_content_check') {
+    if (!existsSync(INTERNAL_SCRIPT_PATHS.forbidden_content_check)) {
+      return buildJsonResult({
+        error: 'forbidden_content_check tool is unavailable because scripts/forbidden-content-check.mjs is missing in this workspace.',
+      }, true);
+    }
+
     return runNodeCommand('forbidden_content_check', ['./scripts/forbidden-content-check.mjs']);
   }