@ryuenn3123/agentic-senior-core 4.2.7 → 4.2.9

package/.agent-context/prompts/bootstrap-design.md

@@ -29,7 +29,7 @@ Check `docs/design-intent.json`:
 4. Record `motionPaletteDecision` before UI code; product categories are heuristics, not style presets.
 5. Encode `repoEvidence.designEvidenceSummary` when onboarding or detector evidence exists.
 6. Keep both design docs synchronized after implementation.
-7. Complete the Section 3-5 gates from `research-design.md` before UI implementation: `conceptualAnchor.categoryCodes.candidateEntries`, `conceptualAnchor.morphologicalExploration` (selected and uncomfortable combinations), and `conceptualAnchor.anchorCandidates.candidates` (exactly five, each with the strengthened rename test recorded).
+7. Complete the Section 3 gate from `research-design.md` before UI implementation: `conceptualAnchor.categoryCodes` (at least three category defaults to avoid with rejection notes), `conceptualAnchor.anchorReference` (one concrete, googleable reference), and four creative commitments (typography, palette, motion, composition) recorded in design docs.
 8. Set `derivedTokenLogic.tokenContinuityClassification` for each of typography, palette, motion, and spacing. Use `anchor-derived` only when the token choice is causally tied to the anchor's real-world reality. Use `continuity-retained` when the token is kept from a previous design iteration without re-derivation. Use `newly-introduced` when the token is fresh but not anchor-derived. If any token category is `continuity-retained`, the typography, palette, or motion entry in `researchDossier.metadata.antiRepeatLedger` stays as historical record, and the classification declares the retention is intentional with explicit rationale recorded in the matching `derivationSource` field.
 9. After agent and user select an anchor, set `researchDossier.metadata.researchVerifiedAt` to today's ISO date and flip `status` from any seed value to `active`. This closes the freshness window for additive UI tasks within `freshnessWindowDays`.
 10. Complete the Live Source Freshness Gate from `research-design.md` before claiming that a visual pattern, library, browser feature, accessibility requirement, or interaction style is current. Record `sourceFreshness` and `evidenceTable[]` in `docs/design-intent.json`.

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/research-design.md

@@ -120,122 +120,52 @@ Reference material is fuel for variance, not a style source.
 
 If references are not provided by the user and web search is unavailable, set `referenceIntakeStatus` to `internal-evidence-only` and constrain Sections 3 to 5 to repo evidence and project docs.
 
-## Section 3 — Category Code Identification
+## Section 3 — Creative Direction
 
-Before exploring variance, name the cliches the product category will default to without intervention. These are the patterns reviewers recognize on sight as "the standard look" for the category.
+Before UI code, commit to a specific visual direction. The agent tends to converge toward generic, "on distribution" outputs. In frontend design this creates what users call the "AI slop" aesthetic. This section exists to prevent that.
 
-This list becomes `categoryCodes` in the design-intent.json. Specificity standard: a category code is only valid if someone can recognize the exact cliche from the text description alone, without seeing the UI and without knowing the product name.
+### 3a. Category defaults to avoid
 
-Fails specificity:
-- `clean typography` (too abstract, applies to anything)
-- `modern color palette` (not falsifiable)
-- `smooth animations` (describes nothing specific)
+Name at least three specific cliches your product category will fall into without intervention. Be specific enough that someone unfamiliar with the project can visualize the exact aesthetic trap from the text alone.
 
-Examples of cliches described with sufficient specificity. Read carefully: these examples illustrate the description format. They are themselves AI-defaultable cliches of their categories. They are NOT target aesthetics. They are not aesthetic candidates for any product. They appear here so you can see what specificity reads like; you are not allowed to ship them.
+Common AI-safe cliches to name and reject when your product sits anywhere near them:
 
-The three example categories below were chosen specifically because they are unlikely to overlap with common software products, to prevent leakage:
-
-- `children's storybook illustration site: hand-painted gouache textures with irregular hand-lettered titles, off-grid spreads with whitespace gutters, page-turn pacing rather than scroll` (instantly recognizable as kids book category default)
-- `luxury car configurator: full-bleed monochrome photography on black, ultra-thin sans-serif tracked wide, slow horizontal scroll with locked vertical alignment, micro-counters that tick instead of slide` (instantly recognizable as luxury auto category default)
-- `academic philosophy journal: high-contrast black-on-cream, book-class serif body at 11pt with generous leading, footnote markers with hover panels, numbered table-of-contents navigation, no hero imagery` (instantly recognizable as academic journal category default)
-
-Anti-leakage rule: listing a cliche is identifying a trap, not endorsing an aesthetic. If your product happens to fall in one of the example categories above, the matching cliche still must appear in your `categoryCodes` AND must carry an explicit rejection note. The same applies to the AI-safe defaults below.
-
-Common AI-safe cliches you must list and reject if your product is anywhere near them. Software products almost always pattern-match one of these without intervention:
-
-- `dev-tool default: condensed tabular numerics with minimal chrome and monospace code blocks on dark slate background, sans-serif metadata at 11–12px, monochrome status dots, single-line settings rows`
-- `AI-startup landing default: purple-to-pink gradient hero with floating 3D glass cards, sans-serif display type at 700–900 weight, vague hero copy, three-up feature grid below the fold`
-- `health/wellness app default: mint accent on white surface with coral status indicators, rounded pill-shaped buttons, friendly sans-serif at high weight, soft drop shadows on cards`
-- `SaaS admin default: left-side icon-only nav, top utility bar, three-card KPI row above a single data table, neutral grey-on-white with one accent color, modal-driven detail flows`
+- `dev-tool default: condensed tabular numerics with minimal chrome and monospace code blocks on dark slate background, sans-serif metadata at 11-12px, monochrome status dots`
+- `AI-startup landing default: purple-to-pink gradient hero with floating 3D glass cards, sans-serif display type at 700-900 weight, vague hero copy, three-up feature grid`
+- `SaaS admin default: left-side icon-only nav, top utility bar, three-card KPI row above a single data table, neutral grey-on-white with one accent color`
 - `marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid`
 
-If you find yourself describing your selected direction in the same shape as any of these, you have inverted the test. Revise.
-
-Self-test: read each category code aloud to someone unfamiliar with the project.
-
-- If they cannot visualize a specific aesthetic direction from the text alone, the code is too abstract. Revise until it passes.
-- If they say "yeah that's basically the X cliche", the description is specific enough. The cliche then belongs on your reject list, not on your candidate list.
-
-Output: at least three category codes per product surface in `categoryCodes`. Each entry must pass the specificity self-test, must include the one-sentence reason that pattern is the default for the category, and must include an explicit one-sentence rejection note ("I will not ship this; here is the trap it sets") so the cliche cannot quietly become the target.
-
-### Dimensional split (mandatory)
-
-Category codes must be broken down by dimension. Do not collapse multiple dimensions into a single category-level cliche. Each cluster lists the patterns that the product category will default to without intervention.
-
-- `typographyClusters`: font family combinations that are the category default. Be explicit about font families. Name the actual trio or pair that this product's category currently defaults to, derived from live portfolio observation for THIS task. Do not anchor on examples from other categories or other timeframes.
-- `paletteClusters`: palette signatures that are the category default.
-- `layoutClusters`: layout patterns that are the category default.
-- `motionClusters`: motion signatures that are the category default.
-- `imageryClusters`: image style or visual treatment that is the category default.
-
-Self-check before proceeding to Section 4: do the typography choices the agent is about to commit to in `derivedTokenLogic` (or downstream token sections) overlap with any item in `typographyClusters`? If yes, the agent must either:
-
-1. Flag the typography as a continuity choice with an explicit rationale, set `derivedTokenLogic.tokenContinuityClassification.typography` to `continuity-retained`, and record the reason that font family swap is deferred. The previous typography ledger entry stays as historical record; the classification declares the retention is intentional. OR
-2. Revise the typography pick to escape the autopilot cluster and set `tokenContinuityClassification.typography` to `anchor-derived` only when the new choice is causally tied to the anchor's real-world reality.
-
-This self-check applies to every dimension, not only typography. Do not let an output token match a category-code item from the agent's own list without explicit (1) or (2) treatment per dimension. Pretending continuity is derivation is the failure mode this gate exists to prevent.
-
-## Section 4 — Morphological Exploration
-
-A morphological matrix forces the design space to be explored beyond the first idea.
-
-Choose five or six dimensions that matter for this product. Common dimensions include hierarchy, density, type role contrast, motion language, state vocabulary, material logic, color behavior, composition rhythm, and interaction grammar. Generate four or five values per dimension. Do not include the category code defaults from Section 3 as values; the matrix is for variance, not for ratifying the cliche.
-
-Output a 5x5 or 6x5 morphological matrix. Then:
-
-1. Highlight the combination that becomes the basis for Section 5 candidates.
-2. Highlight at least ONE combination that feels instinctively wrong or uncomfortable but CAN be argued with product logic. This is the uncomfortable combination requirement.
-
-The uncomfortable combination exists to prove the matrix actually spans the design space. If every combination in the matrix feels safe, shippable, and unobjectionable, the matrix has not explored far enough; it is clustering in the safe-creative zone.
-
-Rules for the uncomfortable combination:
-- It must be genuinely uncomfortable (the agent's first reaction is "this would not work").
-- It must be arguable (the agent can construct a two-sentence product-logic justification for why it could work despite discomfort).
-- It must not be random noise (uncomfortable plus unjustifiable equals waste, not exploration).
-- The user is not required to choose it. Its purpose is to prove the design space was explored beyond the comfort boundary.
-
-If the agent cannot produce an uncomfortable-but-arguable combination, the dimensions chosen are too narrow. Widen at least one dimension and regenerate the matrix.
+Each category default must include a one-sentence rejection note explaining the trap it sets.
 
-Output: `morphologicalExploration` block with `dimensions[]`, `matrix` (rendered as a Markdown table inside `docs/DESIGN.md` and as a structured array inside `docs/design-intent.json`), `selectedCombination`, `uncomfortableCombination` ({ `combinationLabel`, `discomfortReason`, `productLogicJustification` }).
+Output: `categoryCodes[]` with at least three entries in `docs/design-intent.json`. Each entry has `description`, `categoryDefaultReason`, and `rejectionNote`.
 
-## Section 5 — Anchor Candidates
+### 3b. Anchor reference
 
-From the selected morphological combination, generate exactly five anchor candidates. An anchor is a real-world reference whose mechanics, hierarchy, density, type roles, state language, and motion behavior translate into UI grammar without copying its surface.
+Pick one concrete, googleable real-world reference whose mechanics (not surface) translate to your UI. The anchor must be specific enough that renaming the product to a different category breaks coherence.
 
-Hard constraints on anchors:
-- The anchor must be concrete and googleable. "Modern", "clean", "premium", "expressive", "minimal", "bold", "futuristic", "elegant" are not anchors.
-- Specific premium digital products are valid anchors when the borrowed element is an interaction mechanic, hierarchy pattern, or motion behavior — not a palette or brand. Be specific enough that the reference fails the rename test.
-- Do not default to spatial place metaphors such as room, darkroom, control room, counting room, war room, studio, lab, cockpit, command center. Use them only when the product genuinely depends on a physical place model. Prefer artifacts, custody flows, instruments, data behaviors, materials, editorial systems, service rituals, or interaction mechanisms.
-- Pass the strengthened rename test: mentally rename the product to three genuinely different categories. Categories must be remote from each other and from the actual product (for example, if the product is a health app, test against fintech dashboard, kids educational game, and industrial equipment monitoring console).
+Hard constraints:
+- Reject generic quality words as anchors: "modern", "clean", "premium", "expressive", "minimal", "bold", "futuristic", "elegant" are not anchors.
+- Specific premium digital products are valid anchors when the borrowed element is an interaction mechanic, hierarchy pattern, or motion behavior -- not a palette or brand.
+- Do not default to spatial place metaphors (room, darkroom, control room, studio, lab, cockpit, command center). Prefer artifacts, workflows, instruments, data behaviors, materials, editorial systems, or interaction mechanisms.
+- Draw from IDE themes, cultural aesthetics, cinematic campaigns, editorial systems, material artifacts, or specific product experiences for inspiration.
 
-Strengthened rename test scoring:
-- UI still coherent in zero of three renamed categories: anchor is highly specific. STRONG PASS.
-- UI still coherent in one of three: anchor is specific enough. PASS with note.
-- UI still coherent in two of three: anchor is too generic. REVISE the anchor to add product-specific constraints until it fails in at least two of three.
-- UI still coherent in three of three: anchor is category-agnostic. DISCARD immediately.
+Output: `conceptualAnchor.anchorReference` in `docs/design-intent.json`.
 
-Test-category freshness: do not reuse the same three test categories across every anchor. Pick fresh categories per anchor. Categories used in earlier examples (fintech dashboard, kids educational game, industrial equipment monitoring console) are listed only as illustration of "remote from each other"; they are not a fixed test triple. Reusing the same triple lets the agent memorize the pass condition instead of stress-testing the anchor.
+### 3c. Four creative commitments (record before coding)
 
-The three test categories must be stated explicitly in the dossier alongside each anchor's rename test result. This makes the test auditable by human reviewers.
+1. **Typography**: Choose distinctive fonts with meaningful role contrast. Avoid overused families (Inter, Roboto, Arial, Space Grotesk, system fonts). Pick choices that elevate the aesthetic. Record one variable-axis or pairing decision.
+2. **Color and palette**: Commit to a cohesive product-derived palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Name what product evidence makes the palette fit and one color behavior that would not transfer to another category.
+3. **Motion and interaction**: Define one signature motion behavior more specific than "smooth." Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use CSS-only or a modern motion library.
+4. **Composition**: Make one composition choice that avoids interchangeable card stacks. Create atmosphere and depth rather than defaulting to solid backgrounds.
 
-For EACH of the five candidates, record:
+Avoid generic AI-generated aesthetics:
+- Overused font families and cliched color schemes (particularly purple gradients)
+- Predictable layouts and cookie-cutter component patterns
+- Solid-color backgrounds without atmosphere or depth
 
-- `anchorReference` (concrete, googleable)
-- `conceptualFamily`
-- `jobFit` (one sentence linking to product)
-- `hierarchyImplication`
-- `densityImplication`
-- `typeImplication` (variable axis or pairing logic, not just family)
-- `stateLanguage` (loading, empty, error, partial, stale, optimistic, success using the anchor's own vocabulary)
-- `motionImplication` (choreography rule, what state change it serves)
-- `whatItRulesOut` (proves variance)
-- `renameTest`:
-  - `testCategories`: three remote categories used for testing
-  - `results`: coherent or incoherent per category, in order
-  - `verdict`: STRONG PASS, PASS, REVISE, or DISCARD
-- `categoryCodeOverlap` check: list any Section 3 category codes this candidate accidentally inherits, with reasoning
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. The agent still tends to converge on common choices across generations; resist this.
 
-Output: `anchorCandidates[]` (length five). Discard any candidate with `verdict: DISCARD` before selection. The selected anchor populates `conceptualAnchor.anchorReference` and `derivedTokenLogic.anchorReference` (they must match exactly).
+Output: Record all four commitments in `docs/design-intent.json` before UI code. The `derivedTokenLogic.tokenContinuityClassification` must classify each of typography, palette, motion, and spacing as `anchor-derived`, `continuity-retained`, or `newly-introduced` with rationale.
 
 ## Done Criteria
 
@@ -243,9 +173,9 @@ The brief is complete when:
 
 1. `productReading` is filled with evidence-backed sentences.
 2. `referenceIntake[]` records the borrowed mechanic and the explicit non-copy boundary per reference (or `referenceIntakeStatus: internal-evidence-only` is set).
-3. `categoryCodes[]` has at least three entries that pass the specificity self-test.
-4. `morphologicalExploration` has a 5x5 or 6x5 matrix, a selected combination, and an uncomfortable combination with the three required fields.
-5. `anchorCandidates[]` has exactly five entries; each has a complete `renameTest`; the selected anchor has `verdict: STRONG PASS` or `verdict: PASS`.
+3. `categoryCodes[]` has at least three entries with rejection notes.
+4. One anchor reference is recorded that passes the specificity test (renaming the product to a different category breaks coherence).
+5. Four creative commitments are recorded with product-derived rationale.
 6. Generic anchors and spatial-place defaults are rejected with the rejection reason recorded.
 
 Only after the brief is complete does the agent move on to `docs/DESIGN.md` and the rest of `docs/design-intent.json` (token logic, motion budget, accessibility policy, review rubric, library decisions, etc., per `bootstrap-design.md`).

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

@@ -74,8 +74,8 @@ Location: `.agent-context/prompts/`. Load the matching prompt only, plus `compac
 - `init-project.md` -> create, build, new project, scaffold
 - `refactor.md` -> refactor, improve, clean up, fix
 - `review-code.md` -> review, audit, check, analyze
-- `bootstrap-design.md` -> ui, ux, layout, screen, tailwind, frontend, redesign (always paired with `research-design.md` for the Section 3-5 dossier gate)
-- `research-design.md` -> design research dossier (Section 3 categoryCodes, Section 4 morphologicalExploration, Section 5 anchorCandidates with strengthened rename test). Loads before `bootstrap-design.md` whenever the dossier is missing, the design contract status is a seed, `researchDossier.metadata.researchVerifiedAt` is null or older than `freshnessWindowDays`, or the user explicitly requests a redesign.
+- `bootstrap-design.md` -> ui, ux, layout, screen, tailwind, frontend, redesign (always paired with `research-design.md` for the Section 3 creative direction gate)
+- `research-design.md` -> design research dossier (Section 3 creative direction: category defaults to avoid, anchor reference, four creative commitments). Loads before `bootstrap-design.md` whenever the dossier is missing, the design contract status is a seed, `researchDossier.metadata.researchVerifiedAt` is null or older than `freshnessWindowDays`, or the user explicitly requests a redesign.
 
 For UI-only work, load `bootstrap-design.md`, `research-design.md`, and `frontend-architecture.md` first; do not eagerly load unrelated backend-only rules unless the request crosses that boundary. The valid style context is current repo evidence, current brief, and current project docs. External references, prior-chat memory, unrelated-project visuals, and remembered screenshots are tainted unless the user makes them current-task constraints. Treat WCAG 2.2 AA as the hard compliance floor and APCA as advisory perceptual tuning only. Do not require screenshot capture as a baseline dependency.
 
@@ -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
@@ -141,7 +141,7 @@ Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
 2. Detect user-explicit redesign first ("redesign from zero", "redesain dari 0", "ulang dari 0", "research ulang", any explicit reset). It bypasses the freshness gate; run research-design.md regardless of dossier age and treat existing direction as anti-repeat ledger input only.
 3. Route by `docs/design-intent.json` state. File missing, status one of `seed-needs-design-synthesis`, `seed-generated-during-init`, `seed-generated-during-upgrade`, OR active with `researchDossier.metadata.researchVerifiedAt` null or older than `freshnessWindowDays` (90): run research-design.md, then bootstrap-design.md, then flip status to active and write today's ISO date to `researchVerifiedAt`. Active and fresh and no explicit redesign: run bootstrap-design.md only for additive UI tasks; do not auto-refresh `researchVerifiedAt`.
 4. Scenario routing: backend-only init then later UI request (Scenario B) requires `npx @ryuenn3123/agentic-senior-core upgrade` to re-sync UI governance when `bootstrap-design.md` or `research-design.md` is missing; upgrade-migrated metadata (Scenario D) and init on existing project that already had design-intent.json (Scenario E) populate the anti-repeat ledger from previous anchor, palette, and motion. Treat every ledger entry as a hard blocklist when running research-design.md.
-5. Anti-repeat ledger contract: read `researchDossier.metadata.antiRepeatLedger` before producing candidates. The five Section 5 anchor candidates must each differ from every blocklisted entry on at least conceptual family, hierarchy implication, and motion implication. Restating an existing direction with new wording is REVISE.
+5. Anti-repeat ledger contract: read `researchDossier.metadata.antiRepeatLedger` before producing candidates. The chosen anchor must differ from every blocklisted entry on at least conceptual family, hierarchy implication, and motion implication. Restating an existing direction with new wording is REVISE.
 6. Include a one-line Motion/Palette Decision before UI code; product categories are heuristics, not style presets. Record one real-world anchor, one signature motion behavior, and one typographic role contrast.
 7. Ensure `docs/design-intent.json` includes `conceptualAnchor.anchorReference`, top-level `derivedTokenLogic`, `researchDossier.metadata`, `libraryResearchStatus`, `libraryDecisions[]`, and motion/palette decisions. Generate or refine `docs/DESIGN.md` plus `docs/design-intent.json` before UI implementation.
 8. Keep context isolated; do not eagerly load unrelated backend-only rules. For broad screens or redesigns, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline; quiet or static surfaces require a concrete product, performance, accessibility, device, or dependency reason.
@@ -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/design-contract/sections/conceptual-anchor.mjs

@@ -3,11 +3,11 @@
  * that force agents to commit to a real-world reference, motion, and typography
  * decision before UI implementation, instead of defaulting to spatial cliches.
  *
- * Carries the Section 3-5 dossier from
+ * Carries the Section 3 dossier from
  * `.agent-context/prompts/research-design.md`:
- *   - categoryCodes (Section 3)
- *   - morphologicalExploration (Section 4)
- *   - anchorCandidates (Section 5)
+ *   - categoryCodes (Section 3a)
+ *   - anchorReference (Section 3b)
+ *   - creativeCommitments (Section 3c)
  */
 
 export function buildConceptualAnchorSection() {
@@ -126,7 +126,6 @@ export function buildConceptualAnchorSection() {
       selfTestRule: 'Read each category code aloud to someone unfamiliar with the project. If they cannot visualize a specific aesthetic direction from the text alone, the code is too abstract; revise. If they say "that is basically the X cliche", the description is specific enough; the cliche then belongs on the reject list with a rejection note, not as a candidate target.',
       requiredFieldsPerEntry: [
         'description',
-        'specificityEvidence',
         'categoryDefaultReason',
         'rejectionNote',
       ],
@@ -139,73 +138,7 @@ export function buildConceptualAnchorSection() {
       ],
       candidateEntries: [],
     },
-    morphologicalExploration: {
-      mode: 'agent-must-complete-before-ui-implementation',
-      blockingByDefault: true,
-      researchBriefSection: 'Section 4',
-      researchBriefPath: '.agent-context/prompts/research-design.md',
-      requiredMatrixShape: '5x5-or-6x5',
-      minimumDimensions: 5,
-      maximumDimensions: 6,
-      valuesPerDimension: 5,
-      forbidCategoryCodeValuesInMatrix: true,
-      requireSelectedCombination: true,
-      requireUncomfortableCombination: true,
-      uncomfortableCombinationRule: 'Highlight at least one combination that feels instinctively wrong or uncomfortable but can be argued with product logic. The uncomfortable combination proves the matrix actually spans the design space; if every combination feels safe, shippable, and unobjectionable, the matrix is clustering in the safe-creative zone.',
-      uncomfortableCombinationRequiredFields: [
-        'combinationLabel',
-        'discomfortReason',
-        'productLogicJustification',
-      ],
-      widenDimensionsWhenUncomfortableCombinationCannotBeProduced: true,
-      seedDimensions: [],
-      seedMatrix: [],
-      selectedCombination: null,
-      uncomfortableCombination: null,
-    },
-    anchorCandidates: {
-      mode: 'agent-must-complete-before-ui-implementation',
-      blockingByDefault: true,
-      researchBriefSection: 'Section 5',
-      researchBriefPath: '.agent-context/prompts/research-design.md',
-      requiredCandidateCount: 5,
-      requiredFieldsPerCandidate: [
-        'anchorReference',
-        'conceptualFamily',
-        'jobFit',
-        'hierarchyImplication',
-        'densityImplication',
-        'typeImplication',
-        'stateLanguage',
-        'motionImplication',
-        'whatItRulesOut',
-        'renameTest',
-        'categoryCodeOverlap',
-      ],
-      renameTest: {
-        mode: 'strengthened',
-        requiredTestCategoryCount: 3,
-        testCategoryDistanceRule: 'The three test categories must be remote from each other and from the actual product (for example, if the product is a health app, test against fintech dashboard, kids educational game, and industrial equipment monitoring console).',
-        testCategoryFreshnessRule: 'Pick fresh test categories per anchor. Reusing the same triple across every anchor lets the agent memorize the pass condition instead of stress-testing the anchor. The illustrative triple in testCategoryDistanceRule is not a fixed test set.',
-        verdictScoring: {
-          'STRONG PASS': 'UI still coherent in 0 of 3 renamed categories.',
-          PASS: 'UI still coherent in 1 of 3. Pass with note.',
-          REVISE: 'UI still coherent in 2 of 3. Anchor is too generic. Revise the anchor to add product-specific constraints until it fails in at least 2 of 3.',
-          DISCARD: 'UI still coherent in 3 of 3. Anchor is category-agnostic. Discard immediately.',
-        },
-        requireTestCategoriesRecordedInDossier: true,
-        auditableByHumanReviewer: true,
-        renameTestRequiredFields: [
-          'testCategories',
-          'results',
-          'verdict',
-        ],
-      },
-      categoryCodeOverlapRule: 'List any Section 3 category codes this candidate accidentally inherits, with reasoning.',
-      forbiddenSelectedVerdicts: ['DISCARD'],
-      requiredSelectedVerdicts: ['STRONG PASS', 'PASS'],
-      candidates: [],
-    },
+
     finalAnchorContract: {
       requiredFields: [
         'name',

package/lib/cli/project-scaffolder/design-contract/validation/anchor-validators.mjs

@@ -213,8 +213,6 @@ export function validateConceptualAnchor(designIntentContract, validationErrors)
   validateVisualRiskBudgetAndLiteralPolicy(conceptualAnchor, validationErrors);
   validateFinalAnchorContract(conceptualAnchor, validationErrors);
   validateCategoryCodes(conceptualAnchor, validationErrors, { isSeedStatus });
-  validateMorphologicalExploration(conceptualAnchor, validationErrors, { isSeedStatus });
-  validateAnchorCandidates(conceptualAnchor, validationErrors, { isSeedStatus });
   return validationErrors;
 }
 
@@ -281,11 +279,10 @@ function validateCategoryCodes(conceptualAnchor, validationErrors, options = {})
   if (
     !Array.isArray(categoryCodes.requiredFieldsPerEntry)
     || !categoryCodes.requiredFieldsPerEntry.includes('description')
-    || !categoryCodes.requiredFieldsPerEntry.includes('specificityEvidence')
     || !categoryCodes.requiredFieldsPerEntry.includes('categoryDefaultReason')
     || !categoryCodes.requiredFieldsPerEntry.includes('rejectionNote')
   ) {
-    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.requiredFieldsPerEntry must require description, specificityEvidence, categoryDefaultReason, and rejectionNote.');
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.requiredFieldsPerEntry must require description, categoryDefaultReason, and rejectionNote.');
   }
   if (!Array.isArray(categoryCodes.forbiddenPlaceholderPhrases) || categoryCodes.forbiddenPlaceholderPhrases.length === 0) {
     validationErrors.push('designIntent.conceptualAnchor.categoryCodes.forbiddenPlaceholderPhrases must list the abstract phrases that fail the specificity self-test.');
@@ -295,162 +292,3 @@ function validateCategoryCodes(conceptualAnchor, validationErrors, options = {})
   }
 }
 
-function validateMorphologicalExploration(conceptualAnchor, validationErrors, options = {}) {
-  const { isSeedStatus = false } = options;
-  const morphologicalExploration = conceptualAnchor.morphologicalExploration;
-  if (!morphologicalExploration || typeof morphologicalExploration !== 'object') {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration must exist (Section 4 of research-design.md).');
-    return;
-  }
-  if (morphologicalExploration.mode !== 'agent-must-complete-before-ui-implementation') {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.mode must equal "agent-must-complete-before-ui-implementation".');
-  }
-  if (morphologicalExploration.blockingByDefault !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.blockingByDefault must equal true.');
-  }
-  if (morphologicalExploration.researchBriefSection !== 'Section 4') {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.researchBriefSection must equal "Section 4".');
-  }
-  if (morphologicalExploration.requiredMatrixShape !== '5x5-or-6x5') {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requiredMatrixShape must equal "5x5-or-6x5".');
-  }
-  if (morphologicalExploration.minimumDimensions !== 5) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.minimumDimensions must equal 5.');
-  }
-  if (morphologicalExploration.maximumDimensions !== 6) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.maximumDimensions must equal 6.');
-  }
-  if (morphologicalExploration.valuesPerDimension !== 5) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.valuesPerDimension must equal 5.');
-  }
-  if (morphologicalExploration.forbidCategoryCodeValuesInMatrix !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.forbidCategoryCodeValuesInMatrix must equal true so Section 3 cliches do not re-enter the matrix as values.');
-  }
-  if (morphologicalExploration.requireSelectedCombination !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requireSelectedCombination must equal true.');
-  }
-  if (morphologicalExploration.requireUncomfortableCombination !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.requireUncomfortableCombination must equal true.');
-  }
-  if (!hasNonEmptyString(morphologicalExploration.uncomfortableCombinationRule)) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombinationRule must be a non-empty string explaining why the uncomfortable combination is required.');
-  }
-  if (
-    !Array.isArray(morphologicalExploration.uncomfortableCombinationRequiredFields)
-    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('combinationLabel')
-    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('discomfortReason')
-    || !morphologicalExploration.uncomfortableCombinationRequiredFields.includes('productLogicJustification')
-  ) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombinationRequiredFields must include combinationLabel, discomfortReason, and productLogicJustification.');
-  }
-  if (morphologicalExploration.widenDimensionsWhenUncomfortableCombinationCannotBeProduced !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.widenDimensionsWhenUncomfortableCombinationCannotBeProduced must equal true.');
-  }
-
-  if (morphologicalExploration.uncomfortableCombination !== null && typeof morphologicalExploration.uncomfortableCombination === 'object') {
-    const uncomfortableCombination = morphologicalExploration.uncomfortableCombination;
-    if (!hasNonEmptyString(uncomfortableCombination.combinationLabel)) {
-      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.combinationLabel must be a non-empty string.');
-    }
-    if (!hasNonEmptyString(uncomfortableCombination.discomfortReason)) {
-      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.discomfortReason must be a non-empty string.');
-    }
-    if (!hasNonEmptyString(uncomfortableCombination.productLogicJustification)) {
-      validationErrors.push('designIntent.conceptualAnchor.morphologicalExploration.uncomfortableCombination.productLogicJustification must be a non-empty string.');
-    }
-  }
-}
-
-function validateAnchorCandidates(conceptualAnchor, validationErrors, options = {}) {
-  const { isSeedStatus = false } = options;
-  const anchorCandidates = conceptualAnchor.anchorCandidates;
-  if (!anchorCandidates || typeof anchorCandidates !== 'object') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates must exist (Section 5 of research-design.md).');
-    return;
-  }
-  if (anchorCandidates.mode !== 'agent-must-complete-before-ui-implementation') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.mode must equal "agent-must-complete-before-ui-implementation".');
-  }
-  if (anchorCandidates.blockingByDefault !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.blockingByDefault must equal true.');
-  }
-  if (anchorCandidates.researchBriefSection !== 'Section 5') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.researchBriefSection must equal "Section 5".');
-  }
-  if (anchorCandidates.requiredCandidateCount !== 5) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredCandidateCount must equal 5.');
-  }
-  if (
-    !Array.isArray(anchorCandidates.requiredFieldsPerCandidate)
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('anchorReference')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('jobFit')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('hierarchyImplication')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('densityImplication')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('typeImplication')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('stateLanguage')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('motionImplication')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('whatItRulesOut')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('renameTest')
-    || !anchorCandidates.requiredFieldsPerCandidate.includes('categoryCodeOverlap')
-  ) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredFieldsPerCandidate must list the full anchor dossier fields including renameTest and categoryCodeOverlap.');
-  }
-
-  const renameTest = anchorCandidates.renameTest;
-  if (!renameTest || typeof renameTest !== 'object') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest must exist.');
-    return;
-  }
-  if (renameTest.mode !== 'strengthened') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.mode must equal "strengthened".');
-  }
-  if (renameTest.requiredTestCategoryCount !== 3) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.requiredTestCategoryCount must equal 3.');
-  }
-  if (!hasNonEmptyString(renameTest.testCategoryDistanceRule)) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.testCategoryDistanceRule must be a non-empty string requiring remote categories.');
-  }
-  if (!hasNonEmptyString(renameTest.testCategoryFreshnessRule)) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.testCategoryFreshnessRule must be a non-empty string preventing reuse of the same test triple across every anchor.');
-  }
-  if (!renameTest.verdictScoring || typeof renameTest.verdictScoring !== 'object') {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.verdictScoring must define STRONG PASS, PASS, REVISE, and DISCARD verdicts.');
-  } else {
-    for (const verdict of ['STRONG PASS', 'PASS', 'REVISE', 'DISCARD']) {
-      if (!hasNonEmptyString(renameTest.verdictScoring[verdict])) {
-        validationErrors.push(`designIntent.conceptualAnchor.anchorCandidates.renameTest.verdictScoring["${verdict}"] must be a non-empty string.`);
-      }
-    }
-  }
-  if (renameTest.requireTestCategoriesRecordedInDossier !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.requireTestCategoriesRecordedInDossier must equal true.');
-  }
-  if (renameTest.auditableByHumanReviewer !== true) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.auditableByHumanReviewer must equal true.');
-  }
-  if (
-    !Array.isArray(renameTest.renameTestRequiredFields)
-    || !renameTest.renameTestRequiredFields.includes('testCategories')
-    || !renameTest.renameTestRequiredFields.includes('results')
-    || !renameTest.renameTestRequiredFields.includes('verdict')
-  ) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.renameTest.renameTestRequiredFields must include testCategories, results, and verdict.');
-  }
-
-  if (!hasNonEmptyString(anchorCandidates.categoryCodeOverlapRule)) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.categoryCodeOverlapRule must be a non-empty string.');
-  }
-  if (!Array.isArray(anchorCandidates.forbiddenSelectedVerdicts) || !anchorCandidates.forbiddenSelectedVerdicts.includes('DISCARD')) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.forbiddenSelectedVerdicts must include "DISCARD".');
-  }
-  if (
-    !Array.isArray(anchorCandidates.requiredSelectedVerdicts)
-    || !anchorCandidates.requiredSelectedVerdicts.includes('STRONG PASS')
-    || !anchorCandidates.requiredSelectedVerdicts.includes('PASS')
-  ) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.requiredSelectedVerdicts must include "STRONG PASS" and "PASS".');
-  }
-  if (!Array.isArray(anchorCandidates.candidates)) {
-    validationErrors.push('designIntent.conceptualAnchor.anchorCandidates.candidates must be an array (empty in the seed; populated by the agent).');
-  }
-}

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -60,12 +60,10 @@ function buildDesignIntentContractObject({
   return {
     _gate: {
       phase: 'scaffold-only',
-      instruction: 'DO NOT fill conceptualAnchor, derivedTokenLogic, or any token values until research-design.md Sections 3, 4, and 5 are complete. Do not simplify or rewrite this scaffold. Fill fields in-place after research.',
+      instruction: 'DO NOT fill conceptualAnchor, derivedTokenLogic, or any token values until research-design.md Section 3 is complete. Do not simplify or rewrite this scaffold. Fill fields in-place after research.',
       blockedFields: [
         'conceptualAnchor.anchorReference',
         'conceptualAnchor.categoryCodes.candidateEntries',
-        'conceptualAnchor.morphologicalExploration.selectedCombination',
-        'conceptualAnchor.anchorCandidates.candidates',
         'derivedTokenLogic.colorDerivationSource',
         'motionPaletteDecision'
       ]

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.9",
   "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',
@@ -366,20 +392,18 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'default component-kit styling without product rationale',
       'genericity findings that cannot name the exact drift signal',
       'research-design.md',
-      'Section 3-5 gates from `research-design.md`',
+      'Section 3 gate from `research-design.md`',
     ],
   },
   {
     path: '.agent-context/prompts/research-design.md',
     snippets: [
       '# Research-Design Brief',
-      '## Section 3 — Category Code Identification',
-      '## Section 4 — Morphological Exploration',
-      '## Section 5 — Anchor Candidates',
-      'specificity self-test',
-      'uncomfortable combination',
-      'STRONG PASS',
-      'DISCARD',
+      '## Section 3 — Creative Direction',
+      '### 3a. Category defaults to avoid',
+      '### 3b. Anchor reference',
+      '### 3c. Four creative commitments',
+      'AI slop',
       'Anti-Repeat Ledger Gate',
       'Live Source Freshness Gate',
       'rolling-current',
@@ -388,13 +412,8 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'Research vocabulary is internal-only',
       'previousAnchors',
       'previousMotionSignatures',
-      'Dimensional split',
-      'typographyClusters',
-      'paletteClusters',
-      'layoutClusters',
-      'motionClusters',
-      'imageryClusters',
       'tokenContinuityClassification',
+      'categoryCodes',
     ],
   },
   {

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);