@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

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

@@ -190,6 +190,7 @@ export function buildDesignBootstrapPrompt({
     '29. repoEvidence when onboarding or detector evidence exists',
     '',
     '## Mechanical Gates',
+    '0. Read `.agent-context/prompts/research-design.md` first. Sections 3 (Category Code Identification), 4 (Morphological Exploration), and 5 (Anchor Candidates) are gates: each must produce an auditable artifact before UI implementation.',
     '1. Do not copy external style guides.',
     '2. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
     '3. Do not choose final style, library, palette, typography, motion, or layout from this offline scaffold.',
@@ -238,6 +239,13 @@ export function buildDesignBootstrapPrompt({
     '40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
     '41. Use external websites and benchmark examples as candidate evidence for constraints, mechanics, and quality bars only; do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
     '',
+    '## Research-Design Brief Gates (research-design.md)',
+    '42. Section 3 — Category Code Identification: list at least three category codes per product surface in `conceptualAnchor.categoryCodes.candidateEntries`. Each entry must record `description`, `specificityEvidence`, `categoryDefaultReason`, and `rejectionNote`. The specificity floor is: a reader unfamiliar with the project must be able to visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name. Reject placeholder phrases like "clean typography", "modern color palette", or "smooth animations". Anti-leakage rule: listing a cliche identifies a trap, not a target; the example cliches in the brief are not aesthetic candidates for any project. If the project pattern-matches a common AI-safe default (dev-tool dark slate, AI-startup purple-pink gradient, health-app mint, SaaS admin three-card KPI, marketing-site three-tile hero), name that cliche in `candidateEntries` with an explicit rejection note.',
+    '43. Section 4 — Morphological Exploration: build a 5x5 or 6x5 matrix in `conceptualAnchor.morphologicalExploration`. Choose 5 or 6 dimensions and 5 values per dimension. Do not seed the matrix with the Section 3 category codes as values. Highlight the selected combination, and ALSO highlight at least one uncomfortable combination that feels instinctively wrong but can be argued with product logic. The uncomfortable combination must record `combinationLabel`, `discomfortReason`, and `productLogicJustification`. If you cannot produce an uncomfortable-but-arguable combination, the dimensions are too narrow; widen at least one and regenerate.',
+    '44. Section 5 — Anchor Candidates: produce exactly five entries in `conceptualAnchor.anchorCandidates.candidates`. Each candidate must record `anchorReference`, `conceptualFamily`, `jobFit`, `hierarchyImplication`, `densityImplication`, `typeImplication`, `stateLanguage`, `motionImplication`, `whatItRulesOut`, `renameTest`, and `categoryCodeOverlap`.',
+    '45. Strengthened rename test: rename the product to three genuinely different categories that are remote from each other and from the actual product. Pick fresh test categories per anchor; do not reuse the same triple across every anchor. Record the three test categories explicitly in the dossier so a human reviewer can audit them. Score the result: 0/3 coherent equals STRONG PASS, 1/3 equals PASS, 2/3 equals REVISE, 3/3 equals DISCARD. Never select an anchor with verdict DISCARD; revise REVISE candidates until they fail in at least 2 of 3 categories.',
+    '46. Make `conceptualAnchor.anchorReference` and `derivedTokenLogic.anchorReference` match the selected anchor exactly. The selected anchor must have verdict STRONG PASS or PASS.',
+    '',
     '## Creative Ambition Floor',
     'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
     'The ambition floor is not a fixed aesthetic. Quiet, dense, utilitarian, or text-heavy interfaces are allowed when the product requires them, but they still need a project-specific visual decision and a real reason for omitting richer motion, 3D, canvas, WebGL, scroll choreography, or animation libraries.',
@@ -290,6 +298,7 @@ export function buildDesignBootstrapPrompt({
     '13. Preserve externalResearchIntake so user-provided research becomes reviewed evidence without turning into an offline style or dependency preset.',
     '14. Preserve conceptualAnchor so prompt-only UI work has one cohesive non-template concept instead of a mixed collection of bold but unrelated visual decisions.',
     '15. Record conceptualAnchor.agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, visualRiskBudget, motionRiskBudget, and cohesionChecks so the final UI cannot quietly fall back to a timid dashboard/admin mental model.',
+    '15a. Record conceptualAnchor.categoryCodes.candidateEntries (Section 3 of research-design.md), conceptualAnchor.morphologicalExploration with selectedCombination and uncomfortableCombination (Section 4), and conceptualAnchor.anchorCandidates.candidates with full renameTest results (Section 5) before UI implementation.',
     '16. Preserve derivedTokenLogic, libraryResearchStatus, and libraryDecisions so token choices and dependency uncertainty stay visible before implementation.',
     '16a. Preserve designFlexibilityPolicy so the machine contract guides consistency without freezing literal anchor artifacts, exact token primitives, or component-kit visual language.',
     '17. Preserve productionContentPolicy so UI output is ship-ready and not a testing-looking scaffold.',

package/mcp.json

@@ -1,25 +1,36 @@
 {
   "version": "1.1",
   "name": "agentic-senior-core",
-  "description": "MCP configuration for governance-aware diagnostics, scoped rule loading, and self-healing workflows with dynamic knowledge injection.",
+  "description": "MCP configuration for governance-aware diagnostics and scoped rule loading. Five knowledge layers ship as concrete file-backed surfaces today; four additional layers are declared as planned dynamic surfaces. See docs/architecture-vision.md for the roadmap.",
   "knowledgeLayers": {
     "enabled": true,
-    "description": "9-layer dynamic knowledge injection for AI agents",
+    "description": "Knowledge layer registry. 5 layers are file-backed and active today (rules, prompts, state, policies, project-context). 4 layers are reserved as planned dynamic surfaces (stack-strategies, architecture-playbooks, execution-contracts, governance-modes) and resolve to no-op until implemented in a later phase.",
+    "implementedLayerCount": 5,
+    "plannedLayerCount": 4,
+    "totalDeclaredLayers": 9,
+    "roadmapReference": "docs/architecture-vision.md",
     "layers": {
       "rules": {
         "path": ".agent-context/rules",
         "count": 15,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "stack-strategies": {
         "path": "dynamic",
         "autoLoad": true,
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for runtime-decision-signal cache derived from detected project stack."
       },
       "architecture-playbooks": {
         "path": "dynamic",
         "autoLoad": true,
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for structural-planning playbooks derived from repo evidence."
       },
       "execution-contracts": {
         "path": "dynamic",
@@ -29,12 +40,16 @@
           "review-checklists",
           "policies"
         ],
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-3-anti-halu",
+        "rationale": "Reserved for active-contract resolution. Today the agent reads prompts, review-checklists, and policies directly from their file-backed layers; the dedicated execution-contract resolver is planned for the validation MCP tools in Phase 3."
       },
       "prompts": {
         "path": ".agent-context/prompts",
         "count": 4,
         "autoLoad": true,
+        "status": "implemented",
         "templates": [
           "init-project",
           "bootstrap-design",
@@ -50,22 +65,28 @@
           "regulated",
           "startup"
         ],
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for governance-mode selection metadata. Profile selection lives in policy files today and the mode-resolver is planned."
       },
       "state": {
         "path": ".agent-context/state",
         "count": 22,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "policies": {
         "path": ".agent-context/policies",
         "count": 1,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "project-context": {
         "path": "docs",
         "count": 0,
         "autoLoad": false,
+        "status": "implemented",
         "sources": [
           "project-brief",
           "architecture-decision-record",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.50",
+  "version": "4.0.1",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -56,7 +56,14 @@
     "audit:rules-guardian": "node ./scripts/rules-guardian-audit.mjs",
     "audit:explain-on-demand": "node ./scripts/explain-on-demand-audit.mjs",
     "audit:single-source-lazy-loading": "node ./scripts/single-source-lazy-loading-audit.mjs",
+    "audit:cache-layer-contract": "node ./scripts/audit-cache-layer-contract.mjs",
+    "audit:reflection-citations": "node ./scripts/audit-reflection-citations.mjs",
+    "audit:caching-scope-hygiene": "node ./scripts/audit-caching-scope-hygiene.mjs",
+    "audit:release-bundle": "node ./scripts/audit-release-bundle.mjs",
+    "audit:file-size": "node ./scripts/audit-file-size.mjs",
+    "audit:rule-id-uniqueness": "node ./scripts/audit-rule-id-uniqueness.mjs",
     "audit:v3-purge": "node ./scripts/v3-purge-audit.mjs",
+    "build:release-bundle": "node ./scripts/build-release-benchmark-bundle.mjs",
     "sync:adapters": "node ./scripts/sync-thin-adapters.mjs",
     "check:adapters": "node ./scripts/sync-thin-adapters.mjs --check",
     "gate:release": "node ./scripts/release-gate.mjs && node ./scripts/forbidden-content-check.mjs",
@@ -69,11 +76,19 @@
     "benchmark:gate": "node ./scripts/benchmark-gate.mjs",
     "benchmark:intelligence": "node ./scripts/benchmark-intelligence.mjs",
     "benchmark:continuity": "node ./scripts/memory-continuity-benchmark.mjs",
+    "benchmark:cache-phase-2": "node ./benchmarks/token-usage/run-cache-simulation.mjs",
+    "benchmark:anti-halu": "node ./benchmarks/anti-halu/run-benchmark.mjs",
     "report:quality-trend": "node ./scripts/quality-trend-report.mjs",
     "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "clean:local": "node ./scripts/clean-local-artifacts.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/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.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/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./tests/research-dossier-migration.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.96.0",
+    "@google/genai": "^2.3.0",
+    "tiktoken": "^1.0.22",
+    "yaml": "^2.9.0"
   }
 }

package/scripts/audit-cache-layer-contract.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * audit-cache-layer-contract.mjs
+ *
+ * Phase 2 cache-layer integrity gate. Validates provider cache metadata,
+ * fixture segmentation, and the emitted cache simulation JSON without calling
+ * provider APIs.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  CACHE_LAYER_DEFINITIONS,
+  CACHE_LAYER_IDS,
+  validateCacheLayerContract,
+} from '../benchmarks/token-usage/lib/cache-layer-contract.mjs';
+import {
+  CACHE_MATRIX_VERIFIED_AT,
+  PROVIDER_CACHE_MATRIX,
+  listProviderCacheEntries,
+} from '../benchmarks/token-usage/lib/provider-cache-matrix.mjs';
+import {
+  buildCacheLayeredScenarioPrompts,
+  loadFixtures,
+} from '../benchmarks/token-usage/runners/_shared.mjs';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const DEFAULT_RESULT_PATH = join(REPOSITORY_ROOT, 'benchmarks', 'results', 'cache-phase-2-2026-05-16.json');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const REQUIRED_PROVIDER_KEYS = [
+  'provider',
+  'sourceUrl',
+  'sourceType',
+  'verifiedAt',
+  'cacheMode',
+  'minimumCacheableTokens',
+  'costModel',
+];
+
+function addViolation(violations, kind, detail, context = {}) {
+  violations.push({ kind, detail, ...context });
+}
+
+function validateProviderMatrix(violations) {
+  for (const entry of listProviderCacheEntries()) {
+    for (const key of REQUIRED_PROVIDER_KEYS) {
+      if (!(key in entry)) {
+        addViolation(violations, 'provider-metadata.missing-key', `${entry.provider} missing ${key}`, { provider: entry.provider });
+      }
+    }
+
+    if (entry.sourceType === 'official-docs') {
+      if (typeof entry.sourceUrl !== 'string' || !entry.sourceUrl.startsWith('https://')) {
+        addViolation(violations, 'provider-metadata.invalid-source-url', `${entry.provider} official sourceUrl must be https`, { provider: entry.provider });
+      }
+      if (entry.verifiedAt !== CACHE_MATRIX_VERIFIED_AT) {
+        addViolation(violations, 'provider-metadata.invalid-verified-at', `${entry.provider} verifiedAt must be ${CACHE_MATRIX_VERIFIED_AT}`, { provider: entry.provider });
+      }
+    }
+
+    if (entry.provider === 'anthropic') {
+      const ttlOptions = entry.costModel?.ttlOptions;
+      if (ttlOptions?.['5m']?.writeMultiplier !== 1.25 || ttlOptions?.['5m']?.readMultiplier !== 0.1) {
+        addViolation(violations, 'provider-metadata.anthropic-5m-multiplier', 'Anthropic 5m cache multipliers drifted');
+      }
+      if (ttlOptions?.['1h']?.writeMultiplier !== 2.0 || ttlOptions?.['1h']?.readMultiplier !== 0.1) {
+        addViolation(violations, 'provider-metadata.anthropic-1h-multiplier', 'Anthropic 1h cache multipliers drifted');
+      }
+    }
+
+    if (['openai', 'gemini'].includes(entry.provider) && entry.costModel?.accurate !== false) {
+      addViolation(violations, 'provider-metadata.fake-universal-pricing', `${entry.provider} must not claim universal accurate pricing`, { provider: entry.provider });
+    }
+  }
+}
+
+function validateLayerDefinitions(violations) {
+  const definitionIds = Object.keys(CACHE_LAYER_DEFINITIONS);
+  const uniqueDefinitionIds = new Set(definitionIds);
+  if (definitionIds.length !== uniqueDefinitionIds.size) {
+    addViolation(violations, 'layer-definition.duplicate-id', 'Cache layer definition IDs must be unique');
+  }
+
+  const expectedIds = [
+    CACHE_LAYER_IDS.STATIC_PREFIX,
+    CACHE_LAYER_IDS.SEMI_STATIC_CONTEXT,
+    CACHE_LAYER_IDS.DYNAMIC_SUFFIX,
+  ];
+  if (JSON.stringify(definitionIds) !== JSON.stringify(expectedIds)) {
+    addViolation(violations, 'layer-definition.unexpected-order', `Expected ${expectedIds.join(', ')}, got ${definitionIds.join(', ')}`);
+  }
+}
+
+function validateFixtureSegmentation(violations) {
+  const fixtures = loadFixtures();
+  let auditedScenarioCount = 0;
+  for (const fixture of fixtures) {
+    const layered = buildCacheLayeredScenarioPrompts(fixture);
+    const scenarios = [
+      { name: 'always_included', contract: layered.alwaysIncluded },
+      { name: 'with_loaded_rules', contract: layered.withLoadedRules },
+    ];
+
+    for (const scenario of scenarios) {
+      auditedScenarioCount += 1;
+      try {
+        validateCacheLayerContract(scenario.contract);
+      } catch (error) {
+        addViolation(violations, 'fixture-segmentation.invalid-contract', error.message, {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+
+      const layerIds = scenario.contract.layers.map((layer) => layer.id);
+      if (new Set(layerIds).size !== layerIds.length) {
+        addViolation(violations, 'fixture-segmentation.duplicate-layer-id', 'Fixture contract contains duplicate layer IDs', {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+
+      for (const layer of [
+        scenario.contract.layer_1_static_prefix,
+        scenario.contract.layer_2_semi_static_context,
+      ]) {
+        if (layer.content.includes(fixture.user_message)) {
+          addViolation(violations, 'fixture-segmentation.dynamic-leak', `Fixture user message leaked into ${layer.id}`, {
+            fixture_id: fixture.id,
+            scenario: scenario.name,
+          });
+        }
+      }
+
+      if (scenario.contract.layer_3_dynamic_suffix.content.trim().length === 0) {
+        addViolation(violations, 'fixture-segmentation.missing-dynamic-layer', 'Layer 3 dynamic suffix is empty', {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+    }
+  }
+  return { fixtureCount: fixtures.length, auditedScenarioCount };
+}
+
+function validateSimulationResultJson(violations, resultPath = DEFAULT_RESULT_PATH) {
+  if (!existsSync(resultPath)) {
+    addViolation(violations, 'result-json.missing', `Missing cache simulation result: ${resultPath}`);
+    return { resultPath, resultCount: 0 };
+  }
+
+  const parsed = JSON.parse(readFileSync(resultPath, 'utf8'));
+  if (parsed.report_version !== '2.0.0') {
+    addViolation(violations, 'result-json.schema-version', `Unexpected report_version ${parsed.report_version}`);
+  }
+  if (!Array.isArray(parsed.results) || parsed.results.length === 0) {
+    addViolation(violations, 'result-json.results-empty', 'results must be a non-empty array');
+    return { resultPath, resultCount: 0 };
+  }
+
+  const expectedResultCount = parsed.fixture_count * parsed.provider_count * parsed.scenario_count;
+  if (parsed.results.length !== expectedResultCount) {
+    addViolation(violations, 'result-json.result-count', `Expected ${expectedResultCount} rows, got ${parsed.results.length}`);
+  }
+
+  for (const result of parsed.results) {
+    if (!result.token_counts || !result.economic_projection) {
+      addViolation(violations, 'result-json.missing-separation', 'Result must separate token_counts and economic_projection', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+      continue;
+    }
+    if (typeof result.token_counts.layer_3_dynamic_suffix !== 'number' || result.token_counts.layer_3_dynamic_suffix <= 0) {
+      addViolation(violations, 'result-json.missing-layer-3-tokens', 'Layer 3 token count must be present and positive', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+    }
+    if (result.economic_projection.accurate === true && (!result.source?.sourceUrl || !result.source?.verifiedAt)) {
+      addViolation(violations, 'result-json.accurate-without-source', 'Accurate projection requires official source metadata', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+    }
+    if (['openai', 'gemini'].includes(result.provider) && result.economic_projection.first_request_effective_tokens !== null) {
+      addViolation(violations, 'result-json.fake-openai-gemini-savings', `${result.provider} must not emit exact savings without pricing metadata`, {
+        fixture_id: result.fixture_id,
+        scenario: result.scenario,
+      });
+    }
+  }
+
+  return { resultPath, resultCount: parsed.results.length };
+}
+
+export function runCacheLayerContractAudit({ resultPath = DEFAULT_RESULT_PATH } = {}) {
+  const violations = [];
+  validateProviderMatrix(violations);
+  validateLayerDefinitions(violations);
+  const segmentationStats = validateFixtureSegmentation(violations);
+  const resultStats = validateSimulationResultJson(violations, resultPath);
+
+  return {
+    auditName: 'audit-cache-layer-contract',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    providerCount: Object.keys(PROVIDER_CACHE_MATRIX).length,
+    ...segmentationStats,
+    ...resultStats,
+    violationCount: violations.length,
+    violations,
+    passed: violations.length === 0,
+  };
+}
+
+function main() {
+  const report = runCacheLayerContractAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:cache-layer-contract');
+  console.log('===============================================');
+  console.log(`  Providers:          ${report.providerCount}`);
+  console.log(`  Fixtures:           ${report.fixtureCount}`);
+  console.log(`  Layered scenarios:  ${report.auditedScenarioCount}`);
+  console.log(`  Result rows:        ${report.resultCount}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Cache layer contract audit clean.');
+    process.stderr.write(`AUDIT_CACHE_LAYER_REPORT: ${JSON.stringify({ passed: true, providerCount: report.providerCount, resultCount: report.resultCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.detail}`);
+  }
+  process.stderr.write(`AUDIT_CACHE_LAYER_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-cache-layer-contract.mjs')) {
+  main();
+}