@ryuenn3123/agentic-senior-core 2.0.18 → 2.0.20

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,7 +1,7 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.18
-Timestamp: 2026-04-15T00:04:29.752Z
+Generated by Agentic-Senior-Core CLI v2.0.20
+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,7 +1,7 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.0.18
-Timestamp: 2026-04-15T00:04:29.752Z
+Generated by Agentic-Senior-Core CLI v2.0.20
+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/README.md

@@ -359,7 +359,7 @@ npx @ryuenn3123/agentic-senior-core upgrade --yes
 Our documentation has shifted into dedicated tracks to keep this README light:
 - **[FAQ / Concepts](docs/faq.md)**: Unfamiliar with Stacks, Blueprints, or Guardrails? Stalled on basic logic? Start here.
 - **[Deep Dive / Internals](docs/deep-dive.md)**: Explore the dynamic compiler, severity profiles, MCP integration, and granular LLM overrides here.
-- **[V2 Upgrade Playbook](docs/v2-upgrade-playbook.md)**: Benchmark-driven upgrade execution from antigravity-awesome-skills, awesome-copilot, and MiniMax skills.
+- **[V2 Upgrade Playbook](docs/v2-upgrade-playbook.md)**: Benchmark-driven execution plus profile and preset guidance for common usage patterns.
 - **[Skill Platform](.agent-context/skills/README.md)**: Unified skill packs for frontend, backend, fullstack, CLI, distribution, and review quality with `advance` as the default tier.
       The skill platform is now folder-based, so each domain has its own README and topic docs like a curated skills library.
 

package/lib/cli/commands/init.mjs

@@ -34,6 +34,13 @@ 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,
+} from '../project-scaffolder.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   createTokenOptimizationState,
@@ -58,6 +65,9 @@ export function parseInitArguments(commandArguments) {
     tokenOptimize: true,
     tokenAgent: 'copilot',
     includeMcpTemplate: false,
+    scaffoldDocs: undefined,
+    docsLang: 'en',
+    projectConfig: undefined,
   };
 
   for (let argumentIndex = 0; argumentIndex < commandArguments.length; argumentIndex++) {
@@ -166,6 +176,38 @@ 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';
+      argumentIndex += 1;
+      continue;
+    }
+
+    if (currentArgument.startsWith('--docs-lang=')) {
+      parsedInitOptions.docsLang = currentArgument.split('=')[1] || 'en';
+      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}`);
   }
 
@@ -413,6 +455,46 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       operationMode: 'init',
     });
 
+    // --- Project Documentation Scaffolding ---
+    let scaffoldingResult = null;
+    const shouldOfferScaffolding = initOptions.scaffoldDocs === true
+      || (initOptions.scaffoldDocs !== false && await isDirectoryEffectivelyEmpty(resolvedTargetDirectoryPath) && !(await hasExistingProjectDocs(resolvedTargetDirectoryPath)));
+
+    if (shouldOfferScaffolding) {
+      const userWantsScaffolding = initOptions.scaffoldDocs === true
+        || initOptions.projectConfig
+        || 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);
+        }
+
+        scaffoldingResult = await generateProjectDocumentation(
+          resolvedTargetDirectoryPath,
+          discoveryAnswers,
+          {
+            stackFileName: selectedResolvedStackFileName,
+            blueprintFileName: selectedResolvedBlueprintFileName,
+          }
+        );
+
+        console.log(`\nProject documentation generated in docs/:`);
+        for (const generatedFileName of scaffoldingResult.generatedFileNames) {
+          console.log(`  - docs/${generatedFileName}`);
+        }
+      }
+    }
+
     console.log('\nInitialization complete.');
     console.log(`- Target directory: ${resolvedTargetDirectoryPath}`);
     console.log(`- Profile: ${selectedProfile.displayName}`);
@@ -428,6 +510,9 @@ 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(`- 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 +522,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 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/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',
     '',