@ryuenn3123/agentic-senior-core 2.0.19 → 2.0.21

package/.agent-context/state/benchmark-comparison-schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Benchmark Before-vs-After Comparison",
+  "description": "Schema for comparing benchmark results across releases or configuration changes. Each entry captures quality, bug signal, runtime, and token metrics for a before and after snapshot.",
+  "type": "object",
+  "required": ["schemaVersion", "comparisonId", "generatedAt", "before", "after", "delta"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0.0"
+    },
+    "comparisonId": {
+      "type": "string",
+      "description": "Unique identifier for this comparison run."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "baselineVersion": {
+      "type": "string",
+      "description": "Package version of the before snapshot."
+    },
+    "candidateVersion": {
+      "type": "string",
+      "description": "Package version of the after snapshot."
+    },
+    "comparisonType": {
+      "type": "string",
+      "enum": ["release-to-release", "config-change", "model-swap", "manual"],
+      "description": "What triggered this comparison."
+    },
+    "before": { "$ref": "#/$defs/snapshot" },
+    "after": { "$ref": "#/$defs/snapshot" },
+    "delta": { "$ref": "#/$defs/deltaReport" },
+    "verdict": {
+      "type": "string",
+      "enum": ["pass", "warn", "fail"],
+      "description": "Overall comparison verdict based on threshold policy."
+    },
+    "verdictReason": {
+      "type": "string",
+      "description": "Human-readable explanation of the verdict."
+    }
+  },
+  "$defs": {
+    "snapshot": {
+      "type": "object",
+      "required": ["capturedAt", "quality", "runtime"],
+      "properties": {
+        "capturedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "packageVersion": {
+          "type": "string"
+        },
+        "quality": {
+          "type": "object",
+          "properties": {
+            "top1Accuracy": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Fraction of scenarios where the top-ranked output was correct."
+            },
+            "manualCorrectionRate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "description": "Fraction of outputs requiring human correction."
+            },
+            "averageJudgeScore": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 10,
+              "description": "Mean score across all judge dimensions."
+            },
+            "scenarioCount": {
+              "type": "integer",
+              "minimum": 1
+            }
+          }
+        },
+        "bugSignal": {
+          "type": "object",
+          "properties": {
+            "validationFailures": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of validation check failures."
+            },
+            "securityWarnings": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "deprecationWarnings": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "runtime": {
+          "type": "object",
+          "properties": {
+            "totalDurationMs": {
+              "type": "number",
+              "description": "Total benchmark suite execution time in milliseconds."
+            },
+            "averageScenarioDurationMs": {
+              "type": "number"
+            },
+            "peakMemoryMb": {
+              "type": "number"
+            }
+          }
+        },
+        "token": {
+          "type": "object",
+          "properties": {
+            "nativeSavingsPercent": {
+              "type": "number",
+              "description": "Token savings from native optimization."
+            },
+            "proxySavingsPercent": {
+              "type": "number",
+              "description": "Token savings from external proxy optimization."
+            },
+            "totalInputTokens": {
+              "type": "integer"
+            },
+            "totalOutputTokens": {
+              "type": "integer"
+            }
+          }
+        }
+      }
+    },
+    "deltaReport": {
+      "type": "object",
+      "properties": {
+        "top1AccuracyChange": {
+          "type": "number",
+          "description": "After minus before. Positive means improvement."
+        },
+        "manualCorrectionRateChange": {
+          "type": "number",
+          "description": "After minus before. Negative means improvement."
+        },
+        "averageJudgeScoreChange": {
+          "type": "number"
+        },
+        "validationFailureChange": {
+          "type": "integer"
+        },
+        "totalDurationMsChange": {
+          "type": "number"
+        },
+        "nativeSavingsChange": {
+          "type": "number"
+        },
+        "regressionDetected": {
+          "type": "boolean",
+          "description": "True if any metric crossed a threshold in the wrong direction."
+        },
+        "regressionDetails": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "metric": { "type": "string" },
+              "threshold": { "type": "number" },
+              "actual": { "type": "number" },
+              "direction": { "type": "string", "enum": ["increase", "decrease"] }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.19
+Generated by Agentic-Senior-Core CLI v2.0.21
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/.gemini/instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 08994f6e228b32d415dcc2024f31f0a076119a3cf87a4cd2fd2e78e86e5fbd3e
+Canonical Snapshot SHA256: 2a2a036b4fb90f9e668163b83614f2339044c0d021a6eaf2f380e626dfe72de0
 
 Canonical policy source: [.instructions.md](../.instructions.md).
 

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 08994f6e228b32d415dcc2024f31f0a076119a3cf87a4cd2fd2e78e86e5fbd3e
+Canonical Snapshot SHA256: 2a2a036b4fb90f9e668163b83614f2339044c0d021a6eaf2f380e626dfe72de0
 
 The canonical policy source for this repository is [.instructions.md](../.instructions.md).
 

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.19
+Generated by Agentic-Senior-Core CLI v2.0.21
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 08994f6e228b32d415dcc2024f31f0a076119a3cf87a4cd2fd2e78e86e5fbd3e
+Canonical Snapshot SHA256: 2a2a036b4fb90f9e668163b83614f2339044c0d021a6eaf2f380e626dfe72de0
 
 This file is an adapter entrypoint for agent discovery.
 The canonical policy source is [.instructions.md](.instructions.md).

package/lib/cli/commands/init.mjs

@@ -34,6 +34,14 @@ import { detectProjectContext, buildDetectionSummary, formatDetectionCandidates
 import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
 import { runPreflightChecks } from '../preflight.mjs';
 import { createBackup } from '../backup.mjs';
+import {
+  runProjectDiscovery,
+  generateProjectDocumentation,
+  isDirectoryEffectivelyEmpty,
+  hasExistingProjectDocs,
+  loadProjectConfig,
+  normalizeDocsLanguage,
+} from '../project-scaffolder.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   createTokenOptimizationState,
@@ -58,6 +66,10 @@ export function parseInitArguments(commandArguments) {
     tokenOptimize: true,
     tokenAgent: 'copilot',
     includeMcpTemplate: false,
+    scaffoldDocs: undefined,
+    docsLang: 'en',
+    docsLangProvided: false,
+    projectConfig: undefined,
   };
 
   for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
@@ -166,6 +178,40 @@ export function parseInitArguments(commandArguments) {
       continue;
     }
 
+    if (currentArgument === '--scaffold-docs') {
+      parsedInitOptions.scaffoldDocs = true;
+      continue;
+    }
+
+    if (currentArgument === '--no-scaffold-docs') {
+      parsedInitOptions.scaffoldDocs = false;
+      continue;
+    }
+
+    if (currentArgument === '--docs-lang') {
+      parsedInitOptions.docsLang = commandArguments[argumentIndex + 1] || 'en';
+      parsedInitOptions.docsLangProvided = true;
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--docs-lang=')) {
+      parsedInitOptions.docsLang = currentArgument.split('=')[1] || 'en';
+      parsedInitOptions.docsLangProvided = true;
+      continue;
+    }
+
+    if (currentArgument === '--project-config') {
+      parsedInitOptions.projectConfig = commandArguments[argumentIndex + 1];
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--project-config=')) {
+      parsedInitOptions.projectConfig = currentArgument.split('=')[1];
+      continue;
+    }
+
     throw new Error(`Unknown option: ${currentArgument}`);
   }
 
@@ -173,6 +219,12 @@ export function parseInitArguments(commandArguments) {
     throw new Error('--newbie can only be combined with --profile beginner');
   }
 
+  const normalizedDocsLanguage = normalizeDocsLanguage(parsedInitOptions.docsLang || 'en');
+  if (!normalizedDocsLanguage) {
+    throw new Error('--docs-lang must be one of: en, id');
+  }
+
+  parsedInitOptions.docsLang = normalizedDocsLanguage;
   parsedInitOptions.tokenAgent = normalizeAgentName(parsedInitOptions.tokenAgent);
 
   return parsedInitOptions;
@@ -185,6 +237,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     : true;
   const shouldIncludeMcpTemplate = initOptions.includeMcpTemplate === true;
   const selectedTokenAgentName = normalizeAgentName(initOptions.tokenAgent || 'copilot');
+  const isInteractiveSession = Boolean(stdin.isTTY && stdout.isTTY);
 
   if (resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows' || resolvedTargetDirectoryPath.toLowerCase() === 'c:\\windows\\system32') {
     console.error('\n[FATAL] Target directory resolved to a Windows system folder (C:\\Windows).');
@@ -203,6 +256,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       throw new Error('Preflight checks failed.');
   }
 
+  const wasDirectoryEffectivelyEmpty = await isDirectoryEffectivelyEmpty(resolvedTargetDirectoryPath);
+  const hadExistingProjectDocsBeforeInit = await hasExistingProjectDocs(resolvedTargetDirectoryPath);
+
   const backup = await createBackup(resolvedTargetDirectoryPath);
 
   const userInterface = createInterface({ input: stdin, output: stdout });
@@ -386,6 +442,66 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('Installation will continue, but review these warnings before production use.');
     }
 
+    // --- Project Documentation Scaffolding ---
+    let scaffoldingResult = null;
+    const isFreshProjectTarget = wasDirectoryEffectivelyEmpty && !hadExistingProjectDocsBeforeInit;
+    const shouldOfferScaffolding = initOptions.scaffoldDocs === true
+      || Boolean(initOptions.projectConfig)
+      || (initOptions.scaffoldDocs !== false && isFreshProjectTarget);
+
+    if (shouldOfferScaffolding) {
+      if (initOptions.scaffoldDocs === true && !initOptions.projectConfig && !isInteractiveSession) {
+        throw new Error('Non-interactive scaffolding requires --project-config when --scaffold-docs is enabled.');
+      }
+
+      const userWantsScaffolding = initOptions.scaffoldDocs === true
+        || initOptions.projectConfig
+        || (!isInteractiveSession
+          ? false
+          : await askYesNo(
+            'This is a fresh project. Want me to scaffold project documentation (architecture, database, API contract, flow)?',
+            userInterface,
+            true
+          ));
+
+      if (userWantsScaffolding) {
+        let discoveryAnswers;
+
+        if (initOptions.projectConfig) {
+          discoveryAnswers = await loadProjectConfig(initOptions.projectConfig);
+          console.log(`\nLoaded project configuration from: ${initOptions.projectConfig}`);
+        } else {
+          discoveryAnswers = await runProjectDiscovery(userInterface);
+        }
+
+        const normalizedConfigDocsLanguage = normalizeDocsLanguage(discoveryAnswers.docsLang || '');
+        if (discoveryAnswers.docsLang && !normalizedConfigDocsLanguage) {
+          throw new Error(`Unsupported docs language in project config: ${discoveryAnswers.docsLang}. Supported values: en, id`);
+        }
+
+        const selectedDocsLanguage = (!initOptions.docsLangProvided && normalizedConfigDocsLanguage)
+          ? normalizedConfigDocsLanguage
+          : initOptions.docsLang;
+
+        scaffoldingResult = await generateProjectDocumentation(
+          resolvedTargetDirectoryPath,
+          discoveryAnswers,
+          {
+            stackFileName: selectedResolvedStackFileName,
+            blueprintFileName: selectedResolvedBlueprintFileName,
+          },
+          {
+            docsLanguage: selectedDocsLanguage,
+          }
+        );
+
+        console.log(`\nProject documentation generated in docs/:`);
+        for (const generatedFileName of scaffoldingResult.generatedFileNames) {
+          console.log(`  - docs/${generatedFileName}`);
+        }
+      }
+    }
+
     await compileDynamicContext({
       targetDirectoryPath: resolvedTargetDirectoryPath,
       selectedProfileName,
@@ -428,6 +544,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log(`- Blocking severities: ${formatBlockingSeverities(selectedProfile.blockingSeverities)}`);
     console.log(`- Setup time: ${formatDuration(setupDurationMs)}`);
     console.log('- Generated files: .cursorrules, .windsurfrules, and .agent-context/state/onboarding-report.json');
+    if (scaffoldingResult) {
+      console.log(`- Project docs: ${scaffoldingResult.generatedFileNames.length} files generated in docs/`);
+      console.log(`- Project docs language: ${scaffoldingResult.docsLanguage}`);
+    }
     console.log(`- Repository workflows copied: no (workflows remain source-repo assets)`);
     console.log(`- MCP template file: ${shouldIncludeMcpTemplate ? 'created (.vscode/mcp.json)' : 'not created by default (use --mcp-template)'}`);
     if (isTokenOptimizationEnabled) {
@@ -437,6 +557,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     }
     console.log('\nPlain-language summary:');
     console.log(`I prepared a ${selectedProfile.displayName.toLowerCase()} governance pack for a ${toTitleCase(selectedResolvedStackFileName)} project using the ${toTitleCase(selectedResolvedBlueprintFileName)} blueprint.`);
+    if (scaffoldingResult) {
+      console.log(`I also generated project documentation (${scaffoldingResult.docsLanguage}) based on your project description. AI agents will use docs/ as project context.`);
+    }
     console.log('Your AI tools will now receive one compiled rulebook plus the original source rules, and your review threshold is stored in .agent-context/policies/llm-judge-threshold.json.');
     console.log('MCP server registration is manual inside your IDE settings, even when mcp.json exists.');
   } catch (error) {

package/lib/cli/commands/upgrade.mjs

@@ -37,6 +37,7 @@ import { createBackup } from '../backup.mjs';
 import { performRollback } from '../rollback.mjs';
 import { inferSkillDomainNamesFromSelection } from '../skill-selector.mjs';
 import { evaluateSkillDomainCompatibility } from '../compatibility.mjs';
+import { detectProjectDocTemplateStaleness } from '../project-scaffolder.mjs';
 
 export function parseUpgradeArguments(commandArguments) {
   const parsedUpgradeOptions = {
@@ -134,6 +135,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       resolvedTargetDirectoryPath,
       selectedSkillDomainNames
     );
+    const projectDocStalenessReport = await detectProjectDocTemplateStaleness(resolvedTargetDirectoryPath);
 
     if (compatibilityWarnings.length > 0) {
       console.log('\n[WARN] Compatibility checks reported potential issues for this environment:');
@@ -169,6 +171,20 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     console.log(`- Existing rules lines: ${currentRuleLineCount}`);
     console.log(`- Planned rules lines: ${plannedRuleLineCount}`);
     console.log(`- Rules changed: ${isRulesContentChanged ? 'yes' : 'no'}`);
+    if (projectDocStalenessReport.hasProjectDocs) {
+      console.log(`- Project docs detected: ${projectDocStalenessReport.checkedFileNames.length}`);
+      console.log(`- Project docs expected template version: ${projectDocStalenessReport.expectedTemplateVersion}`);
+      console.log(`- Project docs stale files: ${projectDocStalenessReport.staleFiles.length}`);
+    }
+
+    if (projectDocStalenessReport.staleFiles.length > 0) {
+      console.log('\n[WARN] Some project docs were generated from older template versions:');
+      for (const staleDoc of projectDocStalenessReport.staleFiles) {
+        const detectedVersionLabel = staleDoc.detectedTemplateVersion || 'missing';
+        console.log(`- docs/${staleDoc.fileName} (detected: ${detectedVersionLabel}, expected: ${projectDocStalenessReport.expectedTemplateVersion})`);
+      }
+      console.log('Recommendation: regenerate docs with init --scaffold-docs or update the files manually to match the latest template version.');
+    }
 
     if (upgradeOptions.dryRun) {
       console.log('\nDry run enabled. No files were modified.');

package/lib/cli/compiler.mjs

@@ -236,6 +236,37 @@ export async function buildCompiledRulesContent({
     ].join('\n')
   );
 
+  const projectBriefPath = path.join(resolvedTargetDirectoryPath, 'docs', 'project-brief.md');
+  if (await pathExists(projectBriefPath)) {
+    const projectDocsEntries = ['project-brief.md'];
+    const candidateDocFileNames = [
+      'architecture-decision-record.md',
+      'database-schema.md',
+      'api-contract.md',
+      'flow-overview.md',
+    ];
+
+    for (const candidateFileName of candidateDocFileNames) {
+      const candidateFilePath = path.join(resolvedTargetDirectoryPath, 'docs', candidateFileName);
+      if (await pathExists(candidateFilePath)) {
+        projectDocsEntries.push(candidateFileName);
+      }
+    }
+
+    contextBlocks.push(
+      [
+        '## LAYER 9: PROJECT CONTEXT (MANDATORY)',
+        'These documents describe the specific project being built.',
+        'Read them before writing any application code:',
+        ...projectDocsEntries.map((docFileName, docIndex) => `${docIndex + 1}. docs/${docFileName}`),
+        '',
+        'These docs were generated during project initialization and reflect the architecture,',
+        'database design, API contracts, and application flows chosen for this project.',
+        'Update them as the project evolves. They are living references, not frozen specs.',
+      ].join('\n')
+    );
+  }
+
   return [
     '# AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET',
     '',