@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/scripts/detection-benchmark.mjs

@@ -7,15 +7,6 @@
  * Publishes top-1 accuracy and manual-correction-rate proxy.
  */
 
-const BLUEPRINT_RECOMMENDATIONS = {
-  'typescript.md': 'api-nextjs.md',
-  'python.md': 'fastapi-service.md',
-  'java.md': 'spring-boot-api.md',
-  'php.md': 'laravel-api.md',
-  'go.md': 'go-service.md',
-  'csharp.md': 'aspnet-api.md',
-};
-
 const AMBIGUITY_THRESHOLD = 0.08;
 
 const BENCHMARK_FIXTURES = [
@@ -71,8 +62,7 @@ function detectProjectFromMarkers(markers) {
 
   if (candidates.length === 0) {
     return {
-      recommendedStack: null,
-      recommendedBlueprint: null,
+      detectedStack: null,
       confidenceScore: 0,
       confidenceGap: 0,
       needsManualCorrection: true,
@@ -87,8 +77,7 @@ function detectProjectFromMarkers(markers) {
     : Number(strongestCandidate.confidenceScore.toFixed(2));
 
   return {
-    recommendedStack: strongestCandidate.stackFileName,
-    recommendedBlueprint: BLUEPRINT_RECOMMENDATIONS[strongestCandidate.stackFileName] || null,
+    detectedStack: strongestCandidate.stackFileName,
     confidenceScore: strongestCandidate.confidenceScore,
     confidenceGap,
     needsManualCorrection: confidenceGap < AMBIGUITY_THRESHOLD,
@@ -101,7 +90,7 @@ function runBenchmark() {
 
   const fixtureResults = BENCHMARK_FIXTURES.map((benchmarkFixture) => {
     const detectionResult = detectProjectFromMarkers(benchmarkFixture.markers);
-    const isCorrect = detectionResult.recommendedStack === benchmarkFixture.expectedStack;
+    const isCorrect = detectionResult.detectedStack === benchmarkFixture.expectedStack;
 
     if (isCorrect) {
       passingFixtureCount += 1;
@@ -114,7 +103,7 @@ function runBenchmark() {
     return {
       fixtureName: benchmarkFixture.fixtureName,
       expectedStack: benchmarkFixture.expectedStack,
-      detectedStack: detectionResult.recommendedStack,
+      detectedStack: detectionResult.detectedStack,
       confidenceGap: detectionResult.confidenceGap,
       needsManualCorrection: detectionResult.needsManualCorrection,
       isCorrect,

package/scripts/documentation-boundary-audit.mjs

@@ -29,7 +29,7 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'public-surface',
     requirement: 'Public surface changes must update README.md, CHANGELOG.md, or docs/* in the same scope.',
-    suggestedDocumentationUpdates: [
+    requiredDocumentationUpdates: [
       'README.md',
       'CHANGELOG.md',
       'docs/architecture-decision-record.md',
@@ -45,7 +45,7 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'api-contract',
     requirement: 'API endpoint or contract changes must update API/OpenAPI documentation in the same scope.',
-    suggestedDocumentationUpdates: [
+    requiredDocumentationUpdates: [
       'docs/api-contract.md',
       'docs/flow-overview.md',
       '.agent-context/rules/api-docs.md',
@@ -67,7 +67,7 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'database-structure',
     requirement: 'Database structure changes must update schema or migration documentation in the same scope.',
-    suggestedDocumentationUpdates: [
+    requiredDocumentationUpdates: [
       'docs/database-schema.md',
       'docs/flow-overview.md',
       '.agent-context/rules/database-design.md',
@@ -163,8 +163,8 @@ function isDocumentationFilePath(filePath) {
 
 function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles) {
   const boundaryChangedFiles = changedFiles.filter((filePath) => boundaryRule.trigger(filePath));
-  const expectedDocumentationPaths = Array.isArray(boundaryRule.suggestedDocumentationUpdates)
-    ? boundaryRule.suggestedDocumentationUpdates
+  const expectedDocumentationPaths = Array.isArray(boundaryRule.requiredDocumentationUpdates)
+    ? boundaryRule.requiredDocumentationUpdates
     : [];
 
   if (boundaryChangedFiles.length === 0) {
@@ -177,14 +177,14 @@ function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
       documentationFiles: [],
       expectedDocumentationPaths,
       missingDocumentationUpdates: false,
-      suggestedActions: [],
+      requiredActions: [],
       details: 'Boundary not triggered by changed scope.',
     };
   }
 
   const matchingDocumentationFiles = changedDocumentationFiles.filter((filePath) => boundaryRule.docsMatcher(filePath));
   const boundaryPassed = matchingDocumentationFiles.length > 0;
-  const suggestedActions = boundaryPassed
+  const requiredActions = boundaryPassed
     ? []
     : [
       `Update one or more boundary docs: ${expectedDocumentationPaths.join(', ')}`,
@@ -204,7 +204,7 @@ function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
     documentationFiles: matchingDocumentationFiles,
       expectedDocumentationPaths,
       missingDocumentationUpdates: !boundaryPassed,
-      suggestedActions,
+      requiredActions,
     details,
   };
 }
@@ -225,7 +225,7 @@ function runDocumentationBoundaryAudit() {
       requirement: boundaryResult.requirement,
       changedFiles: boundaryResult.changedFiles,
       expectedDocumentationPaths: boundaryResult.expectedDocumentationPaths,
-      suggestedActions: boundaryResult.suggestedActions,
+      requiredActions: boundaryResult.requiredActions,
       diagnosticCode: `BOUNDARY_${boundaryResult.boundaryName.toUpperCase().replace(/-/g, '_')}_DOCS_SYNC_REQUIRED`,
     }));
 

package/scripts/explain-on-demand-audit.mjs

@@ -39,7 +39,7 @@ const REQUIRED_PR_CHECKLIST_SNIPPETS = [
 ];
 
 const REQUIRED_REVIEW_PROMPT_SNIPPETS = [
-  'Enforce explain-on-demand state visibility: default responses must avoid unnecessary state-file internals, state internals are exposed only on explicit request, and diagnostic mode must explain relevant state decisions when needed.',
+  'Review the code with a production-risk mindset.',
 ];
 
 const INTERNAL_STATE_SIGNAL_PATTERNS = [
@@ -225,11 +225,11 @@ function assertSnippetCoverage(sourceLabel, sourcePath, requiredSnippets, failur
 }
 
 function buildDefaultResponseSummary(onboardingReport) {
-  const selectedStack = String(onboardingReport?.selectedStack || 'unknown-stack').trim() || 'unknown-stack';
-  const selectedBlueprint = String(onboardingReport?.selectedBlueprint || 'unknown-blueprint').trim() || 'unknown-blueprint';
+  const runtimeDecision = String(onboardingReport?.runtimeDecision?.mode || onboardingReport?.selectedStack || 'unknown-runtime-decision').trim() || 'unknown-runtime-decision';
+  const architectureDecision = String(onboardingReport?.architectureDecision?.mode || onboardingReport?.selectedBlueprint || 'unknown-architecture-decision').trim() || 'unknown-architecture-decision';
   const selectedProfile = String(onboardingReport?.selectedProfile || 'unknown-profile').trim() || 'unknown-profile';
 
-  return `Active setup summary: stack=${selectedStack}, blueprint=${selectedBlueprint}, profile=${selectedProfile}.`;
+  return `Active setup summary: runtimeDecision=${runtimeDecision}, architectureDecision=${architectureDecision}, profile=${selectedProfile}.`;
 }
 
 function detectInternalSignals(textValue) {
@@ -240,14 +240,14 @@ function detectInternalSignals(textValue) {
 function buildDiagnosticDecisionSummaries(onboardingReport) {
   const explanations = [];
 
-  const selectedStack = String(onboardingReport?.selectedStack || '').trim();
-  if (selectedStack) {
-    explanations.push(`Stack decision: selectedStack=${selectedStack}.`);
+  const runtimeDecision = String(onboardingReport?.runtimeDecision?.mode || onboardingReport?.selectedStack || '').trim();
+  if (runtimeDecision) {
+    explanations.push(`Runtime decision: ${runtimeDecision}.`);
   }
 
-  const selectedBlueprint = String(onboardingReport?.selectedBlueprint || '').trim();
-  if (selectedBlueprint) {
-    explanations.push(`Blueprint decision: selectedBlueprint=${selectedBlueprint}.`);
+  const architectureDecision = String(onboardingReport?.architectureDecision?.mode || onboardingReport?.selectedBlueprint || '').trim();
+  if (architectureDecision) {
+    explanations.push(`Architecture decision: ${architectureDecision}.`);
   }
 
   const selectedProfile = String(onboardingReport?.selectedProfile || '').trim();
@@ -423,4 +423,4 @@ function runAudit() {
   process.exit(reportPayload.passed ? 0 : 1);
 }
 
-runAudit();
+runAudit();

package/scripts/forbidden-content-check.mjs

@@ -15,22 +15,22 @@ const FORBIDDEN_PATTERNS = [
   {
     name: 'Hardcoded API Key',
     regex: /api_?key\s*[:=]\s*['"][a-zA-Z0-9_\-]{16,}['"]/i,
-    suggestion: 'API Keys must be provided via environment variables (process.env) or config files, never hardcoded.'
+    requiredAction: 'API Keys must be provided via environment variables (process.env) or config files, never hardcoded.'
   },
   {
     name: 'Hardcoded Password',
     regex: /password\s*[:=]\s*['"][^'"]+['"]/i,
-    suggestion: 'Passwords must be injected via secret managers or environment variables.'
+    requiredAction: 'Passwords must be injected via secret managers or environment variables.'
   },
   {
     name: 'Absolute Local Desktop Path',
     regex: /file:\/\/\/?([c-zC-Z]:|\/Users\/|\/home\/)/,
-    suggestion: 'Do not commit local absolute file paths (e.g. file:///C:/Users). Use relative paths or process.cwd().'
+    requiredAction: 'Do not commit local absolute file paths. Use relative paths or process.cwd().'
   },
   {
     name: 'Stray Breakpoint (debugger)',
     regex: /\bdebugger\s*;?/,
-    suggestion: 'Remove debug breakpoints before publishing to production.'
+    requiredAction: 'Remove debug breakpoints before publishing to production.'
   }
 ];
 
@@ -48,7 +48,7 @@ function scanFile(filePath) {
           line: i + 1,
           content: line.trim().substring(0, 80), // truncate long lines
           rule: pattern.name,
-          suggestion: pattern.suggestion
+          requiredAction: pattern.requiredAction
         });
       }
     }
@@ -97,12 +97,12 @@ async function runCheck() {
 
       if (violations.length > 0) {
         const relPath = relative(ROOT_DIR, file);
-        console.error(`\n❌ FORBIDDEN CONTENT DETECTED IN: ${relPath}`);
+        console.error(`\nFORBIDDEN CONTENT DETECTED IN: ${relPath}`);
 
         for (const v of violations) {
           console.error(`   Line ${v.line}: [${v.rule}]`);
           console.error(`   > ${v.content}`);
-          console.error(`   Action required: ${v.suggestion}`);
+          console.error(`   Action required: ${v.requiredAction}`);
           totalViolations++;
         }
       }
@@ -112,10 +112,10 @@ async function runCheck() {
   console.log(`\nScanned ${filesScanned.length} files across ${SCAN_DIRECTORIES.length} source directories.`);
 
   if (totalViolations > 0) {
-    console.error(`\n✖ PUBLISH ABORTED: Found ${totalViolations} forbidden content violation(s).`);
+    console.error(`\nPUBLISH ABORTED: Found ${totalViolations} forbidden content violation(s).`);
     process.exit(1);
   } else {
-    console.log('✔ Clean. No forbidden content detected.');
+    console.log('Clean. No forbidden content detected.');
     process.exit(0);
   }
 }

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',
@@ -50,63 +53,77 @@ const REQUIRED_ARCHITECTURE_CHECKLIST_SNIPPETS = [
 ];
 
 const REQUIRED_FRONTEND_RULE_SNIPPETS = [
-  'Frontend Designer Mode (Auto Activation)',
-  'UI scope trigger signals',
-  'visual intent, interaction quality, and conversion clarity',
-  'template-only repetitive outputs',
-  'Context Hygiene and Reference Boundaries (Mandatory)',
-  'Accessibility Split (Mandatory)',
+  'Frontend Design and Interaction Boundaries',
+  'UI work must load the smallest relevant surface, not the entire engineering handbook.',
+  '## Auto Activation',
+  'UI scope triggers:',
+  'Do not use this file to teach generic frontend basics the model already knows.',
+  '## Source Hygiene and Source Boundaries',
+  'This rule guides the LLM; it must not choose the final style',
   'Design continuity is opt-in.',
-  '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.',
-  '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.',
-  'Responsive quality requires layout mutation and task reprioritization across breakpoints. Shrinking the desktop layout is not enough.',
+  'Repo evidence outranks memory residue every time.',
+  '## Accessibility Split',
+  'Treat WCAG 2.2 AA as the hard compliance floor.',
+  'Treat APCA as advisory perceptual tuning only.',
+  '## Anti-Generic UI Boundaries',
+  'Do not default to interchangeable dashboard chrome',
+  'Do not let repeated surfaces share the same visual treatment by habit.',
+  'Do not use default framework button and input treatment as the final UI language.',
+  '## Responsive Mutation Requirements',
+  'Responsive quality is not allowed to be scale-only.',
+  '## Surface and Morphology Requirements',
+  'Define the primary user task or reading path from current evidence',
+  '## Implementation Boundaries',
+  'Do not hardcode Zustand, React Query, smart/dumb component doctrine',
 ];
 
 const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
-  'UI Design Mode is context-isolated by default:',
-  'Responsive Strategy and Cross-Viewport Adaptation Matrix',
+  'This contract is a decision scaffold, not a style preset.',
+  'We guide the agent; we do not pick the final style',
+  'Responsive Recomposition Plan',
   'Token Architecture and Alias Strategy',
-  'tokenSystem',
-  'colorTruth.format',
-  'crossViewportAdaptation.mutationRules.mobile/tablet/desktop',
-  'motionSystem',
-  'componentMorphology',
-  'accessibilityPolicy',
-  'visualQaPolicy',
-  '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',
+  'repoEvidence.designEvidenceSummary',
+  'research current official docs',
+  'Responsive design means recomposition, not resizing.',
+  'agent-chosen visual direction',
+  'viewport mutation rules',
+  'WCAG 2.2 AA is the hard floor',
+  'APCA may be used only as advisory perceptual tuning',
+  'unresearched dependency choices',
+  'default component-kit styling without product rationale',
+  'genericity findings that cannot name the exact drift signal',
 ];
 
 const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [
-  'Advisory-first UI design contract judge.',
+  'Advisory-default UI design contract judge.',
   'Repo-internal workflow audit; no user-facing runtime modes.',
-  'Runs only in advisory mode for this repository workflow.',
+  'genericityAutoFail',
+  'blocking required actions',
   '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',
+  'structuredInspectionAvailable',
+  'applyGenericityAutoFail',
 ];
 
 const REQUIRED_INSTRUCTIONS_SNIPPETS = [
   'UI Design Mode',
+  'Resolve the smallest relevant layer set for the current request.',
   'bootstrap-design.md',
   'frontend-architecture.md',
   'do not eagerly load unrelated backend-only rules',
   'valid style context',
-  'explicitly approved reference systems',
+  'External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted',
   '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 = [
@@ -114,6 +131,9 @@ const REQUIRED_DESIGN_EVIDENCE_SNIPPETS = [
   "source: 'lightweight-static-scan'",
   'cssVariables',
   'componentInventory',
+  'structuredInspection',
+  'classAttributeCount',
+  'inlineStyleObjectCount',
   'tokenBypassSignals',
 ];
 
@@ -243,6 +263,7 @@ function runAudit() {
       extractorIncludesSummaryVersion: designEvidenceExtractorContent.includes('summaryVersion'),
       extractorIncludesCssVariables: designEvidenceExtractorContent.includes('cssVariables'),
       extractorIncludesComponentInventory: designEvidenceExtractorContent.includes('componentInventory'),
+      extractorIncludesStructuredInspection: designEvidenceExtractorContent.includes('structuredInspection'),
       extractorIncludesTokenBypassSignals: designEvidenceExtractorContent.includes('tokenBypassSignals'),
       compilerProjectsFrontendEvidenceMetrics: compilerContent.includes('frontendEvidenceMetrics'),
       compilerProjectsDesignEvidenceSummary: compilerContent.includes('designEvidenceSummary'),

package/scripts/llm-judge.mjs

@@ -242,7 +242,7 @@ You must categorize each violation with a severity level: critical, high, medium
 - critical: Security vulnerabilities (hardcoded secrets, SQL/command injection, missing auth checks, CORS), unvalidated external inputs.
 - high: N+1 database queries, swallowed errors (empty catch blocks without re-throw/recovery), layer boundary violations.
 - medium: TypeScript \`any\` type used without justification, missing test coverage, bad architectural patterns.
-- low: Style preferences, minor naming nitpicks, documentation suggestions, performance micro-optimizations.
+- low: Style preferences, minor naming nitpicks, documentation nitpicks, performance micro-optimizations.
 
 ## Mandatory output format:
 You MUST output your findings in EXACTLY this structure:

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/operations.test.mjs'],
+  cli: ['--test', './tests/cli-smoke.test.mjs'],
+  operations: ['--test', './tests/operations.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, such as 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;
+}