@ryuenn3123/agentic-senior-core 4.2.7 → 4.2.8

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

@@ -11,7 +11,7 @@ Before editing:
 3. If required project docs are missing, stop and bootstrap or update docs first.
 4. If the change touches UI, load .agent-context/prompts/bootstrap-design.md and .agent-context/rules/frontend-architecture.md before editing.
 5. If the change touches a dependency, framework, Docker, runtime, or ecosystem claim, verify current official docs before choosing.
-6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/project-brief.md` is missing, if `docs/architecture-decision-record.md` is missing, if `docs/flow-overview.md` is missing, if `docs/database-schema.md` is missing while the project uses persistent data, if `docs/api-contract.md` is missing while the project exposes API or web application flows, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
 7. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
 8. For backend/API scope, enforce layered boundaries, zero-trust input validation, safe centralized error responses, bounded list reads, transaction safety for multi-write mutations, idempotency for sensitive mutations, and behavior-focused API tests.
 9. Backend/API governance is global and stack-agnostic. Do not create stack-specific adapters or framework-specific rule branches; apply the global rules through the framework already present in the target project.

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

@@ -11,7 +11,7 @@ Before reviewing:
 3. Read .agent-context/review-checklists/architecture-review.md only when architecture or boundaries changed.
 4. Load only the rules relevant to the changed scope.
 5. For UI changes, load .agent-context/prompts/bootstrap-design.md, .agent-context/rules/frontend-architecture.md, docs/DESIGN.md, and docs/design-intent.json when present.
-6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
+6. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/database-schema.md` when persistent data exists; `docs/api-contract.md` when API or web application flows exist; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
 7. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, global domain governance must load lazily based on touched scope, and conflicting duplicate rule instructions must not appear during normal flow.
 
 Prioritize findings in this order:

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

@@ -122,9 +122,13 @@ Run this before declaring a task done. Apply only the sections relevant to the c
 
 - [ ] `.agent-context/rules/` remains the default guidance source for implementation and review.
 - [ ] Security and testing requirements remain mandatory after static template purge.
+- [ ] Coding flow is blocked if `docs/project-brief.md` is missing
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
 - [ ] Coding flow is blocked if root `README.md` is missing
 - [ ] Coding flow is blocked if `docs/doc-index.md` is missing while `docs/` exists
+- [ ] Coding flow is blocked if `docs/flow-overview.md` is missing
+- [ ] Coding flow is blocked if `docs/database-schema.md` is missing while the project uses persistent data
+- [ ] Coding flow is blocked if `docs/api-contract.md` is missing while the project exposes API or web application flows
 - [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing
 
 ## Verdict

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

@@ -121,3 +121,13 @@ keywords:
 7. Reject silent acceptance of duplicate side-effect-producing requests without a key. A caller that retried without a key gets a 400-class response that names the missing key, not a second charge.
 8. Authority for the rules above includes IETF RFC 9110 for HTTP method idempotency semantics and successor specifications for the `Idempotency-Key` request header where the platform standardizes one. Verify the current standardization status at audit time, because the header has been a draft and an RFC at different points in its history.
 <!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+
+## API-013: Documentation Diagram Format (Mandatory)
+
+1. Use Mermaid.js as the default diagram format for all project documentation diagrams: flowcharts, sequence diagrams, ER diagrams, architecture diagrams, C4 model diagrams, and state machine diagrams.
+2. Embed Mermaid diagrams as fenced code blocks with the `mermaid` language tag inside Markdown files.
+3. Do not use PlantUML, ASCII art diagrams, Graphviz DOT, or Structurizr DSL. These formats lack native rendering in GitHub, GitLab, and VS Code Markdown preview, or have lower LLM generation accuracy.
+4. D2 is on the watch list. Do not adopt D2 until GitHub ships native rendering support.
+5. Keep diagrams at macro-architecture and critical-flow level. Do not diagram micro-logic or individual function internals unless the complexity warrants it.
+6. When updating project behavior, update the matching diagrams in the same change. Stale diagrams are worse than no diagrams.
+7. When updating an existing doc that contains prose-only flow descriptions, architecture explanations, or data model descriptions without diagrams, convert the relevant sections to Mermaid diagrams in the same change.

package/AGENTS.md

@@ -103,8 +103,8 @@ Trigger: docs, documentation, dokumen, `docs/*`, architecture docs, flow docs, A
 
 1. Load `architecture.md`, `api-docs.md`, and only additional rules required by scope.
 2. Create or refine required docs first: root `README.md` for every fresh or existing project; `docs/doc-index.md` whenever `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/api-contract.md` for APIs, firmware endpoints, CLI commands, or web application flows; `docs/database-schema.md` for persistent data; and `docs/DESIGN.md` plus `docs/design-intent.json` for UI scope.
-3. Use `docs/doc-index.md` as the compact read-routing map. Add PRD, SRS, technical-design, or separate ERD only when project evidence justifies them.
-4. Write formal project docs in English by default unless the user asks otherwise.
+3. Use Mermaid.js as the default diagram format for all documentation diagrams (flowcharts, sequence, ER, C4, state). Embed as fenced `mermaid` code blocks. Do not use PlantUML, ASCII art diagrams, Graphviz DOT, or Structurizr DSL. When updating existing docs that contain prose-only descriptions, convert relevant sections to Mermaid diagrams in the same change.
+4. Use `docs/doc-index.md` as the compact read-routing map; add PRD, SRS, technical-design, or separate ERD only when justified. Write formal project docs in English by default.
 5. Stop after documentation when the user only asked for docs. Do not write application, firmware, or UI code until the user asks or approves implementation; do not write application, firmware, or UI code before approval.
 
 ### 2. New Project Planning
@@ -163,7 +163,7 @@ Use valid rule IDs only; do not quote full rule prose, expose hidden chain-of-th
 Never claim done without:
 1. Relevant rules applied.
 2. PR and architecture checklists considered.
-3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/architecture-decision-record.md`; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
+3. Universal SOP gates satisfied: public and developer root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/project-brief.md`; `docs/architecture-decision-record.md`; `docs/flow-overview.md`; `docs/database-schema.md` when persistent data exists; `docs/api-contract.md` when API or web application flows exist; plus `docs/DESIGN.md` and `docs/design-intent.json` for UI scope.
 4. If `.agent-context/state/active-memory.json` exists and material project progress happened, refresh it while preserving privacy rules and user-owned entries.
 5. Project validation passed through `npm run validate`.
 

package/lib/cli/adaptive-context/catalog.mjs

@@ -55,6 +55,8 @@ export const RULE_FAMILY_CATALOG = [
       'idempotent',
       'idempotency',
       'documented',
+      'diagram',
+      'mermaid',
     ],
   },
   {

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

@@ -78,10 +78,11 @@ export function buildProjectContextBootstrapPrompt({
     '11. If runtime or framework setup is unresolved, recommend the latest stable compatible option from the brief, constraints, and live official documentation before coding. If an official setup flow yields newer, better-supported defaults than manual package assembly, use that path after approval.',
     '12. Treat topology as an agent decision unless the user explicitly constrained it. If monolith fits, explain why. If a service split fits, document the evidence and service boundary logic.',
     '13. Required docs coverage must include a public and developer README entrypoint, feature plan, architecture rationale, flow, public API or integration contracts when relevant, data model when relevant, UI/design when relevant, security assumptions, testing strategy, runtime/deployment notes, and next validation actions.',
-    '14. README.md must be public and developer friendly, including for private projects: what it is, who it is for, setup, core workflow, configuration, and links to deeper docs. Do not include secrets, internal agent notes, private reasoning, or governance policy dumps.',
-    '15. docs/doc-index.md is the low-token routing map for docs/*. Keep it short, list each active doc, and explain when an agent should read it. Do not make it the source of truth for requirements or architecture.',
-    '16. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
-    '17. Add SRS, PRD, technical-design, or ERD docs only when project evidence triggers them. Use PRD for product-roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and ERD only as a separate file when the schema is too complex for docs/database-schema.md.',
+    '14. Use Mermaid.js as the default diagram format for flow, sequence, ER, architecture, C4, and state diagrams embedded in Markdown docs. Do not use PlantUML, ASCII art diagrams, Graphviz DOT, or Structurizr DSL. When updating existing docs that contain prose-only descriptions, convert relevant sections to Mermaid diagrams in the same change.',
+    '15. README.md must be public and developer friendly, including for private projects: what it is, who it is for, setup, core workflow, configuration, and links to deeper docs. Do not include secrets, internal agent notes, private reasoning, or governance policy dumps.',
+    '16. docs/doc-index.md is the low-token routing map for docs/*. Keep it short, list each active doc, and explain when an agent should read it. Do not make it the source of truth for requirements or architecture.',
+    '17. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
+    '18. Add SRS, PRD, technical-design, or ERD docs only when project evidence triggers them. Use PRD for product-roadmap/user-story ownership, SRS for contractual or multi-stakeholder acceptance criteria, technical-design for non-trivial architecture decisions, and ERD only as a separate file when the schema is too complex for docs/database-schema.md.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.2.7",
+  "version": "4.2.8",
   "type": "module",
   "description": "Change your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/validate/config.mjs

@@ -218,19 +218,28 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
       '### 15. Universal SOP Consolidation',
       'Coding flow is blocked if root `README.md` is missing',
       'Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing',
+      'Coding flow is blocked if `docs/flow-overview.md` is missing',
+      'Coding flow is blocked if `docs/database-schema.md` is missing while the project uses persistent data',
+      'Coding flow is blocked if `docs/api-contract.md` is missing while the project exposes API or web application flows',
       'UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing',
     ],
   },
   {
     path: '.agent-context/prompts/review-code.md',
     snippets: [
-      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (root `README.md`; `docs/doc-index.md` when `docs/` exists; `docs/architecture-decision-record.md`; and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
+      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing',
+      'docs/flow-overview.md',
+      'docs/database-schema.md',
+      'docs/api-contract.md',
     ],
   },
   {
     path: '.agent-context/prompts/refactor.md',
     snippets: [
-      '6. Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing, if `docs/doc-index.md` is missing while `docs/` exists, if `docs/architecture-decision-record.md` is missing, or for UI scope if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
+      'Enforce Universal SOP hard gate: stop implementation if root `README.md` is missing',
+      'docs/flow-overview.md',
+      'docs/database-schema.md',
+      'docs/api-contract.md',
     ],
   },
   {
@@ -247,6 +256,23 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     ],
   },
 ];
+export const REQUIRED_DIAGRAM_FORMAT_SNIPPETS = [
+  {
+    path: '.agent-context/rules/api-docs.md',
+    snippets: [
+      '## API-013: Documentation Diagram Format (Mandatory)',
+      'Mermaid.js as the default diagram format',
+      'Do not use PlantUML',
+      'convert the relevant sections to Mermaid diagrams in the same change',
+    ],
+  },
+  {
+    path: 'lib/cli/project-scaffolder/prompt-builders.mjs',
+    snippets: [
+      'Mermaid.js as the default diagram format',
+    ],
+  },
+];
 export const REQUIRED_TEMPLATE_FREE_BOOTSTRAP_SNIPPETS = [
   {
     path: 'lib/cli/project-scaffolder/storage.mjs',

package/scripts/validate/coverage-checks.mjs

@@ -10,6 +10,7 @@ import {
   REQUIRED_DETECTION_TRANSPARENCY_SNIPPETS,
   REQUIRED_DETERMINISTIC_BOUNDARY_ENFORCEMENT_SNIPPETS,
   REQUIRED_DEVELOPER_FIRST_MENTION_PATTERNS,
+  REQUIRED_DIAGRAM_FORMAT_SNIPPETS,
   REQUIRED_DOCKER_RUNTIME_AUTOMATION_SNIPPETS,
   REQUIRED_HUMAN_WRITING_SNIPPETS,
   REQUIRED_STACK_DECISION_BOUNDARY_SNIPPETS,
@@ -170,6 +171,16 @@ export async function validateUniversalSopConsolidationCoverage(context) {
   });
 }
 
+export async function validateDiagramFormatCoverage(context) {
+  await validateSnippetCoverage({
+    heading: 'Checking documentation diagram format coverage...',
+    coverageRules: REQUIRED_DIAGRAM_FORMAT_SNIPPETS,
+    missingLabel: 'diagram format source',
+    snippetLabel: 'diagram format snippet',
+    context,
+  });
+}
+
 export async function validateTemplateFreeBootstrapCoverage(context) {
   const { ROOT_DIR, fileExists, readTextFile, pass, fail } = context;
 

package/scripts/validate.mjs

@@ -29,6 +29,7 @@ import {
   validateDependencyFreshnessAutomationCoverage,
   validateDetectionTransparencyCoverage,
   validateDeterministicBoundaryEnforcementCoverage,
+  validateDiagramFormatCoverage,
   validateDockerRuntimeAutomationCoverage,
   validateHumanWritingGovernance,
   validateInstructionAdapters,
@@ -688,6 +689,7 @@ async function main() {
   await validateDetectionTransparencyCoverage(coverageValidationContext);
   await validateStackDecisionBoundaryCoverage(coverageValidationContext);
   await validateUniversalSopConsolidationCoverage(coverageValidationContext);
+  await validateDiagramFormatCoverage(coverageValidationContext);
   await validateTemplateFreeBootstrapCoverage(coverageValidationContext);
   await validateUpgradeUiContractWarningCoverage(coverageValidationContext);
   await validateUiDesignAutomationCoverage(coverageValidationContext);