@ryuenn3123/agentic-senior-core 2.5.10 → 2.5.12

package/.agent-context/prompts/refactor.md

@@ -14,12 +14,18 @@ Before making changes:
 2. Read .agent-context/rules/naming-conv.md — fix all naming violations.
 3. Read .agent-context/rules/error-handling.md — fix error handling patterns.
 4. Read .agent-context/stacks/typescript.md — fix TypeScript-specific issues.
+5. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
 
 For every change you make, provide a Reasoning Chain:
 - What was wrong (rule reference)
 - Why it was wrong (explain the risk/problem)
 - What you changed (show the improvement)
 
+Refactor guidance:
+- Prioritize maintainability over compressed one-liners.
+- Prefer explicit readable control flow when short forms hide intent.
+- Do not introduce shared abstractions before patterns are repeated and stable.
+
 Maintain ALL existing functionality. This is a refactor, not a rewrite.
 Add or update tests if the refactored code changes behavior contracts.
 ```

package/.agent-context/prompts/review-code.md

@@ -15,6 +15,7 @@ Use these checklists:
 2. Read .agent-context/review-checklists/security-audit.md — apply every item.
 3. Apply documentation scope rules exactly: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.
 4. Treat scope-style findings as advisory unless they hide factual errors, contract mismatches, or non-negotiable violations.
+5. Enforce documentation hard blockers on changed boundaries: public surface changes, API contract changes, and database structure changes must include synchronized documentation updates.
 
 For EVERY violation found:
 - State the exact file and line

package/.agent-context/review-checklists/architecture-review.md

@@ -29,6 +29,12 @@ Evaluate every item against the current project structure. For each violation, e
 - [ ] **Shared code is genuinely shared** — Not domain-specific code disguised as "common"
 - [ ] **Module size is reasonable** — If a module has 20+ files, consider splitting
 
+## Backend Universal Principles
+
+- [ ] **No clever hacks in backend and shared core modules** — Prefer explicit flow over language tricks that hide intent
+- [ ] **No premature abstraction** — Introduce shared abstractions only after repeated, stable patterns emerge
+- [ ] **Readability over brevity** — Prefer clear multi-line logic over compressed one-liners
+
 ## Dependency Management
 
 - [ ] **No God classes** — No class/file with 500+ lines or 10+ dependencies

package/.agent-context/review-checklists/pr-checklist.md

@@ -40,6 +40,9 @@ VERDICT: PASS / FAIL (X/Y items passed)
 - [ ] Dependencies flow inward (transport → service → repository)
 - [ ] Module boundaries respected (no reaching into another module's internals)
 - [ ] Domain layer has zero external dependencies
+- [ ] No clever hacks in backend and shared core modules (prefer explicit control flow)
+- [ ] No premature abstraction (base classes/util layers created only after repeated stable patterns)
+- [ ] Readability over brevity for maintainability (no compressed one-liners that hide intent)
 
 ### 3. Type Safety (→ stacks/typescript.md)
 - [ ] No `any` type anywhere (use `unknown` + narrowing)
@@ -93,6 +96,10 @@ VERDICT: PASS / FAIL (X/Y items passed)
 ### 10. Documentation
 - [ ] Scope applied: This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations
 - [ ] Style scope review is advisory and does not block merge when API docs are synced in the same commit and contract details are correct
+- [ ] Public surface changes fail review if documentation updates are missing or stale in the same scope
+- [ ] API endpoint/contract changes include synchronized API/OpenAPI documentation updates
+- [ ] Database structure changes include synchronized schema or migration documentation updates
+- [ ] Documentation checks stay boundary-aware and only enforce touched scopes
 - [ ] API endpoints have OpenAPI/Swagger documentation
 - [ ] Complex business logic has comments explaining WHY
 - [ ] Public functions/methods have JSDoc/docstrings

package/.agent-context/rules/api-docs.md

@@ -211,6 +211,25 @@ The spec is a contract. If the contract is wrong, consumers will break.
 "I'll update the docs later" means "the docs will never be updated."
 ```
 
+## Documentation as Hard Rule (Boundary-Aware)
+
+Documentation checks are hard-blocking for contract accuracy, but scope-aware to avoid unnecessary overhead.
+
+### Boundary Triggers
+1. Public surface boundary: exported/public behavior changes in CLI, library, or runtime scripts.
+2. API contract boundary: endpoint, route, controller, or OpenAPI contract changes.
+3. Database structure boundary: schema, migration, repository contract, or persistence model changes.
+
+### Boundary-Aware Enforcement
+1. Only triggered boundaries require synchronized documentation updates.
+2. Untouched boundaries are ignored during the same review run.
+3. Missing docs for a triggered boundary is a blocking failure.
+
+### Required Same-Scope Sync
+1. Public surface changes must update user-facing docs (`README.md`, `CHANGELOG.md`, or `docs/*`).
+2. API contract changes must update API/OpenAPI docs in the same scope.
+3. Database structure changes must update schema/migration documentation in the same scope.
+
 ### Enforcement
 1. API docs live next to the code (same module, same directory)
 2. Docs update in the SAME commit as the endpoint change

package/.agent-context/rules/architecture.md

@@ -3,6 +3,16 @@
 > If your service file imports an HTTP library, your architecture is broken.
 > If your controller contains SQL, you've already lost.
 
+## Universal Backend Principles (Mandatory)
+
+These principles are mandatory for backend and shared core modules.
+
+- No clever hacks. Prefer explicit control flow over language tricks that hide intent.
+- No premature abstraction. Extract shared utilities or base types only after repeated, stable patterns appear.
+- Readability over brevity. Reject compressed one-liners when clearer multi-line logic is easier to review.
+
+If a short and a clear implementation are functionally equivalent, choose the clear implementation.
+
 ## The Core Principle
 
 **Every layer has ONE job. Layer leaks are bugs — not "pragmatic shortcuts."**

package/.agent-context/state/memory-continuity-benchmark.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-17T08:10:30.670Z",
+  "generatedAt": "2026-04-17T09:57:09.275Z",
   "reportName": "memory-continuity-benchmark",
   "schemaVersion": "1.0.0",
   "passed": true,

package/.cursorrules

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

package/.windsurfrules

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.5.10",
+  "version": "2.5.12",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -43,6 +43,7 @@
   "scripts": {
     "init": "node ./bin/agentic-senior-core.js init",
     "audit:frontend-usability": "node ./scripts/frontend-usability-audit.mjs",
+    "audit:documentation-boundary": "node ./scripts/documentation-boundary-audit.mjs",
     "gate:release": "node ./scripts/release-gate.mjs && node ./scripts/forbidden-content-check.mjs",
     "prepublishOnly": "npm run gate:release",
     "sbom:generate": "node ./scripts/generate-sbom.mjs",

package/scripts/documentation-boundary-audit.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+
+/**
+ * documentation-boundary-audit.mjs
+ *
+ * Enforces documentation sync only on changed scope boundaries.
+ * If public surface, API contract, or database structure files change,
+ * matching documentation updates must be present in the same change scope.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPOSITORY_ROOT = resolve(__dirname, '..');
+
+const CORE_DOCUMENTATION_FILES = new Set(['README.md', 'CHANGELOG.md']);
+
+const BOUNDARY_RULES = [
+  {
+    boundaryName: 'public-surface',
+    requirement: 'Public surface changes must update README.md, CHANGELOG.md, or docs/* in the same scope.',
+    trigger(filePath) {
+      return /^(bin\/|lib\/|scripts\/)/.test(filePath) && !isDocumentationFilePath(filePath);
+    },
+    docsMatcher(filePath) {
+      return filePath === 'README.md' || filePath === 'CHANGELOG.md' || filePath.startsWith('docs/');
+    },
+  },
+  {
+    boundaryName: 'api-contract',
+    requirement: 'API endpoint or contract changes must update API/OpenAPI documentation in the same scope.',
+    trigger(filePath) {
+      return !isDocumentationFilePath(filePath)
+        && /(api|openapi|contract|controller|route|endpoint)/i.test(filePath);
+    },
+    docsMatcher(filePath) {
+      return filePath === '.agent-context/rules/api-docs.md'
+        || /^(docs\/.*(api|contract|openapi))/i.test(filePath)
+        || filePath === 'README.md';
+    },
+  },
+  {
+    boundaryName: 'database-structure',
+    requirement: 'Database structure changes must update schema or migration documentation in the same scope.',
+    trigger(filePath) {
+      return !isDocumentationFilePath(filePath)
+        && /(database|schema|migration|repository|sql|prisma|typeorm|knex)/i.test(filePath);
+    },
+    docsMatcher(filePath) {
+      return filePath === '.agent-context/rules/database-design.md'
+        || /^(docs\/.*(database|schema|migration))/i.test(filePath)
+        || filePath === 'README.md';
+    },
+  },
+];
+
+function normalizeFilePath(filePath) {
+  return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function parseGitFileList(rawOutput) {
+  if (typeof rawOutput !== 'string' || rawOutput.trim().length === 0) {
+    return [];
+  }
+
+  return rawOutput
+    .split(/\r?\n/)
+    .map((filePath) => filePath.trim())
+    .filter((filePath) => filePath.length > 0)
+    .map(normalizeFilePath);
+}
+
+function runGitFileQuery(commandArguments) {
+  try {
+    const rawOutput = execFileSync('git', commandArguments, {
+      cwd: REPOSITORY_ROOT,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    return parseGitFileList(rawOutput);
+  } catch {
+    return [];
+  }
+}
+
+function uniqueSorted(filePaths) {
+  return Array.from(new Set(filePaths)).sort((leftPath, rightPath) => leftPath.localeCompare(rightPath));
+}
+
+function collectChangedFiles() {
+  const workingTreeFiles = runGitFileQuery(['diff', '--name-only']);
+  const stagedFiles = runGitFileQuery(['diff', '--name-only', '--cached']);
+  const workingScopeFiles = uniqueSorted([...workingTreeFiles, ...stagedFiles]);
+
+  if (workingScopeFiles.length > 0) {
+    return {
+      source: 'working-tree-and-index',
+      files: workingScopeFiles,
+    };
+  }
+
+  const latestCommitRangeFiles = runGitFileQuery(['diff', '--name-only', 'HEAD~1..HEAD']);
+  if (latestCommitRangeFiles.length > 0) {
+    return {
+      source: 'latest-commit-range',
+      files: uniqueSorted(latestCommitRangeFiles),
+    };
+  }
+
+  const headCommitFiles = runGitFileQuery(['show', '--pretty=format:', '--name-only', 'HEAD']);
+  if (headCommitFiles.length > 0) {
+    return {
+      source: 'head-commit',
+      files: uniqueSorted(headCommitFiles),
+    };
+  }
+
+  return {
+    source: 'none',
+    files: [],
+  };
+}
+
+function isDocumentationFilePath(filePath) {
+  return CORE_DOCUMENTATION_FILES.has(filePath)
+    || filePath.startsWith('docs/')
+    || filePath.startsWith('.agent-context/review-checklists/')
+    || filePath === '.agent-context/rules/api-docs.md'
+    || filePath === '.agent-context/rules/database-design.md';
+}
+
+function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles) {
+  const boundaryChangedFiles = changedFiles.filter((filePath) => boundaryRule.trigger(filePath));
+
+  if (boundaryChangedFiles.length === 0) {
+    return {
+      boundaryName: boundaryRule.boundaryName,
+      requirement: boundaryRule.requirement,
+      triggered: false,
+      passed: true,
+      changedFiles: [],
+      documentationFiles: [],
+      details: 'Boundary not triggered by changed scope.',
+    };
+  }
+
+  const matchingDocumentationFiles = changedDocumentationFiles.filter((filePath) => boundaryRule.docsMatcher(filePath));
+  const boundaryPassed = matchingDocumentationFiles.length > 0;
+
+  const details = boundaryPassed
+    ? `Boundary triggered and synchronized with documentation updates: ${matchingDocumentationFiles.join(', ')}`
+    : 'Boundary triggered without required documentation updates.';
+
+  return {
+    boundaryName: boundaryRule.boundaryName,
+    requirement: boundaryRule.requirement,
+    triggered: true,
+    passed: boundaryPassed,
+    changedFiles: boundaryChangedFiles,
+    documentationFiles: matchingDocumentationFiles,
+    details,
+  };
+}
+
+function runDocumentationBoundaryAudit() {
+  const changedScope = collectChangedFiles();
+  const changedFiles = changedScope.files;
+  const changedDocumentationFiles = changedFiles.filter(isDocumentationFilePath);
+
+  const boundaryResults = BOUNDARY_RULES.map((boundaryRule) => (
+    evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
+  ));
+
+  const failures = boundaryResults
+    .filter((boundaryResult) => boundaryResult.triggered && !boundaryResult.passed)
+    .map((boundaryResult) => {
+      const affectedFiles = boundaryResult.changedFiles.join(', ');
+      return `${boundaryResult.boundaryName}: ${boundaryResult.requirement} Changed files: ${affectedFiles}`;
+    });
+
+  const reportPayload = {
+    generatedAt: new Date().toISOString(),
+    auditName: 'documentation-boundary-audit',
+    source: changedScope.source,
+    changedFileCount: changedFiles.length,
+    changedFiles,
+    boundaryResults,
+    passed: failures.length === 0,
+    failureCount: failures.length,
+    failures,
+  };
+
+  console.log(JSON.stringify(reportPayload, null, 2));
+  process.exit(reportPayload.passed ? 0 : 1);
+}
+
+runDocumentationBoundaryAudit();

package/scripts/release-gate.mjs

@@ -30,6 +30,10 @@ const REQUIRED_SKILL_DOMAINS = [
 const FRONTEND_PARITY_CHECKLIST_PATH = '.agent-context/review-checklists/frontend-skill-parity.md';
 const FRONTEND_EXCELLENCE_RUBRIC_PATH = '.agent-context/review-checklists/frontend-excellence-rubric.md';
 const FRONTEND_AUDIT_SCRIPT_PATH = 'scripts/frontend-usability-audit.mjs';
+const DOCUMENTATION_BOUNDARY_AUDIT_SCRIPT_PATH = 'scripts/documentation-boundary-audit.mjs';
+const BACKEND_ARCHITECTURE_RULE_PATH = '.agent-context/rules/architecture.md';
+const BACKEND_REVIEW_CHECKLIST_PATH = '.agent-context/review-checklists/pr-checklist.md';
+const REFACTOR_PROMPT_PATH = '.agent-context/prompts/refactor.md';
 const REQUIRED_FRONTEND_PARITY_SNIPPETS = [
   'Architecture and Composition',
   'Interaction and Motion',
@@ -37,6 +41,21 @@ const REQUIRED_FRONTEND_PARITY_SNIPPETS = [
   'UX Narrative and Conversion Clarity',
   'Release Evidence',
 ];
+const REQUIRED_BACKEND_ARCHITECTURE_RULE_SNIPPETS = [
+  'No clever hacks.',
+  'No premature abstraction.',
+  'Readability over brevity.',
+  'backend and shared core modules',
+];
+const REQUIRED_BACKEND_REVIEW_CHECKLIST_SNIPPETS = [
+  'No clever hacks in backend and shared core modules',
+  'No premature abstraction (base classes/util layers created only after repeated stable patterns)',
+  'Readability over brevity for maintainability',
+];
+const REQUIRED_REFACTOR_PROMPT_SNIPPETS = [
+  'Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.',
+  'Prioritize maintainability over compressed one-liners.',
+];
 const REQUIRED_FRONTEND_EXCELLENCE_RUBRIC_SNIPPETS = [
   'Visual Direction and Identity',
   'Typography Quality',
@@ -253,6 +272,110 @@ function runReleaseGate() {
     );
   }
 
+  const backendArchitectureRuleContent = readText(BACKEND_ARCHITECTURE_RULE_PATH);
+  if (!backendArchitectureRuleContent) {
+    pushResult(results, false, 'backend-universal-principles-rule-exists', `Missing ${BACKEND_ARCHITECTURE_RULE_PATH}`);
+  } else {
+    pushResult(results, true, 'backend-universal-principles-rule-exists', `${BACKEND_ARCHITECTURE_RULE_PATH} is present`);
+
+    const missingBackendArchitectureRuleSnippets = REQUIRED_BACKEND_ARCHITECTURE_RULE_SNIPPETS.filter(
+      (requiredSnippet) => !backendArchitectureRuleContent.includes(requiredSnippet)
+    );
+
+    if (missingBackendArchitectureRuleSnippets.length === 0) {
+      pushResult(results, true, 'backend-universal-principles-rule-coverage', 'Backend universal rule snippets are complete');
+    } else {
+      pushResult(
+        results,
+        false,
+        'backend-universal-principles-rule-coverage',
+        `Missing backend universal rule snippets: ${missingBackendArchitectureRuleSnippets.join(', ')}`
+      );
+    }
+  }
+
+  const backendReviewChecklistContent = readText(BACKEND_REVIEW_CHECKLIST_PATH);
+  if (!backendReviewChecklistContent) {
+    pushResult(results, false, 'backend-universal-principles-checklist-exists', `Missing ${BACKEND_REVIEW_CHECKLIST_PATH}`);
+  } else {
+    pushResult(results, true, 'backend-universal-principles-checklist-exists', `${BACKEND_REVIEW_CHECKLIST_PATH} is present`);
+
+    const missingBackendChecklistSnippets = REQUIRED_BACKEND_REVIEW_CHECKLIST_SNIPPETS.filter(
+      (requiredSnippet) => !backendReviewChecklistContent.includes(requiredSnippet)
+    );
+
+    if (missingBackendChecklistSnippets.length === 0) {
+      pushResult(results, true, 'backend-universal-principles-checklist-coverage', 'Backend review checklist snippets are complete');
+    } else {
+      pushResult(
+        results,
+        false,
+        'backend-universal-principles-checklist-coverage',
+        `Missing backend review checklist snippets: ${missingBackendChecklistSnippets.join(', ')}`
+      );
+    }
+  }
+
+  const refactorPromptContent = readText(REFACTOR_PROMPT_PATH);
+  if (!refactorPromptContent) {
+    pushResult(results, false, 'backend-universal-principles-refactor-guidance-exists', `Missing ${REFACTOR_PROMPT_PATH}`);
+  } else {
+    pushResult(results, true, 'backend-universal-principles-refactor-guidance-exists', `${REFACTOR_PROMPT_PATH} is present`);
+
+    const missingRefactorPromptSnippets = REQUIRED_REFACTOR_PROMPT_SNIPPETS.filter(
+      (requiredSnippet) => !refactorPromptContent.includes(requiredSnippet)
+    );
+
+    if (missingRefactorPromptSnippets.length === 0) {
+      pushResult(results, true, 'backend-universal-principles-refactor-guidance-coverage', 'Backend refactor guidance snippets are complete');
+    } else {
+      pushResult(
+        results,
+        false,
+        'backend-universal-principles-refactor-guidance-coverage',
+        `Missing backend refactor guidance snippets: ${missingRefactorPromptSnippets.join(', ')}`
+      );
+    }
+  }
+
+  const documentationBoundaryAuditExecution = runMachineReadableScript(DOCUMENTATION_BOUNDARY_AUDIT_SCRIPT_PATH);
+  if (!documentationBoundaryAuditExecution.report) {
+    const failureDetails = documentationBoundaryAuditExecution.executionErrorMessage
+      ? `Documentation boundary audit execution failed before producing a machine-readable report: ${documentationBoundaryAuditExecution.executionErrorMessage}`
+      : 'Documentation boundary audit did not produce machine-readable JSON output';
+    pushResult(results, false, 'documentation-boundary-audit', failureDetails);
+  } else {
+    diagnostics.documentationBoundaryAudit = documentationBoundaryAuditExecution.report;
+    pushResult(
+      results,
+      true,
+      'documentation-boundary-audit',
+      `documentation-boundary-audit executed (passed=${documentationBoundaryAuditExecution.report.passed}, failures=${documentationBoundaryAuditExecution.report.failureCount})`
+    );
+
+    if (documentationBoundaryAuditExecution.report.passed === true) {
+      pushResult(
+        results,
+        true,
+        'documentation-boundary-hard-rule',
+        'Documentation hard-rule passed for all triggered boundaries'
+      );
+    } else {
+      const failedDocumentationBoundaries = Array.isArray(documentationBoundaryAuditExecution.report.failures)
+        ? documentationBoundaryAuditExecution.report.failures
+        : [];
+      const failureSummary = failedDocumentationBoundaries.length > 0
+        ? failedDocumentationBoundaries.join('; ')
+        : 'Documentation boundary audit failed without boundary failure details';
+      pushResult(
+        results,
+        false,
+        'documentation-boundary-hard-rule',
+        `Documentation hard-rule failed: ${failureSummary}`
+      );
+    }
+  }
+
   const frontendParityChecklistContent = readText(FRONTEND_PARITY_CHECKLIST_PATH);
   if (!frontendParityChecklistContent) {
     pushResult(results, false, 'frontend-parity-checklist-exists', `Missing ${FRONTEND_PARITY_CHECKLIST_PATH}`);

package/scripts/validate.mjs

@@ -171,6 +171,7 @@ async function validateRequiredFiles() {
     'scripts/governance-weekly-report.mjs',
     'scripts/mcp-server.mjs',
     'scripts/frontend-usability-audit.mjs',
+    'scripts/documentation-boundary-audit.mjs',
     'scripts/release-gate.mjs',
     'scripts/generate-sbom.mjs',
     'scripts/init-project.sh',