@ryuenn3123/agentic-senior-core 4.3.1 → 4.3.4

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

@@ -1,228 +1,62 @@
-# Bootstrap Dynamic Design Contract
-Use this prompt for UI, UX, frontend layout, screen, Tailwind, animation, 3D, canvas, or redesign work.
+# Design Direction Prompt
 
-Create or refine `docs/DESIGN.md` for human reasoning and `docs/design-intent.json` for machine-readable design intent, guardrails, and review signals.
+Use this prompt for UI, UX, frontend layout, screen, or redesign work. Create or refine `docs/DESIGN.md` before writing UI code.
 
-This contract is a decision scaffold, not a style preset. We guide the agent; we do not pick the final style, stack, framework, palette, typography, layout paradigm, or animation library offline.
+## Authority
 
-## MANDATORY FIRST STEP
+- Use current repo evidence, project docs, and `.agent-context/` as style context.
+- Do not copy layout rhythm, palette, component skin, or brand posture from external references without explicit user approval.
+- WCAG 2.2 AA is the hard compliance floor.
+- Before choosing a new UI library, research current official docs. Do not default to any component kit or styling tool by habit, and do not avoid them when they fit.
 
-Check `docs/design-intent.json`:
-- If `status` contains "seed" OR `researchDossier.metadata.researchVerifiedAt` is null → STOP.
-- Do NOT write UI code.
-- Do NOT fill `conceptualAnchor`, color tokens, typography tokens, or motion tokens with concrete values.
-- **Existing UI exception**: If the project already has a mature UI and the user only asked for an additive feature (not a redesign), you may skip Sections 3-5 of `research-design.md`. Instead, document the existing direction as the `conceptualAnchor`, set token classifications to `continuity-retained`, set `status` to `active`, set `researchVerifiedAt` to today's date, and proceed.
-- Otherwise, run `research-design.md` Sections 3, 4, and 5 first. All three must produce filled artifacts before proceeding.
-- The scaffold file is a structure only. Filling placeholders without completing research is a violation of this contract.
-## Authority
-- Treat `.agent-context/` and current project docs as technical authority.
-- Treat `README.md` as public and developer overview, setup, usage, and user-facing context only. Do not use it as coding, architecture, or design authority when `.agent-context/` gives a stricter rule.
-- Use current repo evidence, product copy, route names, component names, user goals, and existing constraints as the source of truth.
-- Treat prior-chat visuals, unrelated project memory, benchmark screenshots, and famous-product aesthetics as tainted context unless the user explicitly approves continuity.
-- Keep external references non-copying and research vocabulary internal; extract constraints only, and do not leak evidence, dossier, anchor, category-code, morphology, rename-test, or source-freshness labels into UI copy or final rationale unless requested.
-- Before choosing a new UI, animation, scroll, 3D, canvas, chart, icon, styling, or component library, research current official docs.
-- For design research, use the session current date as the rolling freshness reference. Prefer the newest relevant official or primary evidence; never define modern by a fixed calendar range.
-## Required Order
-1. Read `AGENTS.md`, this prompt, `research-design.md`, `../rules/frontend-architecture.md`, current UI code, current project docs, and existing design docs.
-2. Refine existing `docs/DESIGN.md` and `docs/design-intent.json`; do not replace them blindly.
-3. If either design doc is missing, create it before UI implementation.
-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 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`.
-## Internal Vocabulary Rule
-
-The following terms are internal process labels only. 
-They must NEVER appear in:
-- UI copy or component text
-- Public-facing documentation
-- Section headings in DESIGN.md
-- Any text the user reads in the product
-
-Forbidden in output: evidence, dossier, anchor, category-code, 
-morphological, rename test, freshness gate, ledger, accession, 
-provenance, custody, specimen, taxonomy, invariant.
-
-Translate all decisions into plain product language before writing 
-them into DESIGN.md or any UI-facing artifact.
-
-Good: "Typography uses a serif display font paired with monospace for 
-code blocks, creating clear hierarchy between narrative and technical content."
-
-Bad: "The anchor-derived typographic decision pairs a display serif 
-with strict mono per the morphological exploration output."
-
-## Creative Commitment Gate
-Before broad compliance review or UI implementation, record an agent-chosen visual direction in both design docs:
-- one concrete real-world anchor reference
-- one signature motion behavior more specific than "smooth"
-- one typographic decision with meaningful role contrast
-- one authored visual bet visible in the first viewport
-Reject generic anchors. Do not accept "modern", "clean", "premium", "expressive", "minimal", or "bold" as the anchor. Name a specific real-world reference. Valid options include:
-- A specific premium digital experience (e.g., "[Specific Brand] hardware launch page full-bleed section transitions", "[Specific Tool] homepage keyboard-first density rhythm", "[Specific Fintech] marketing site gradient mesh motion")
-- A cinematic campaign or editorial system
-- A material, instrument, or physical mechanism
-
-The reference must be googleable and specific. "Brand-X-style" fails. "[Brand X] M3 reveal page scroll-locked section reveals" passes.
-## Dynamic Avant-Garde Anchor Engine
-If no current-task research or visual reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding.
-Rules:
-- Treat old design docs, prior UI, and scaffold seeds as evidence, not research.
-- Internally consider at least three high-variance anchors.
-- Discard the two safest or most predictable options.
-- Output only the chosen anchor, specific reference point, and rationale.
-- Forbid final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.
-- Do not default to spatial place metaphors such as room, darkroom, control room, counting room, war room, studio, lab, cockpit, or command center. Use them only when the product truly depends on a physical place model.
-- Prefer artifacts, custody flows, instruments, data behaviors, materials, editorial systems, service rituals, or interaction mechanisms over "where the interface lives" as the anchor.
-- Derive typography, spacing, density, color behavior, morphology, motion, and responsive composition from the chosen anchor.
-- Translate the anchor non-literally first. Anchor artifacts are evidence for behavior, hierarchy, density, typography, state language, and motion, not automatic UI chrome.
-- Use reduced-motion fallbacks instead of suppressing motion.
-## Creative Ambition Floor
-Before UI code, record:
-- one product-derived palette move
-- one signature motion, spatial, or interaction behavior
-- one morphology or composition choice that avoids interchangeable card stacks when the product allows it
-- at least three at-a-glance product-specific signals for new screens or broad redesigns
-Do not ship AI-safe UI. Record exact drift signals in `reviewRubric`; at minimum reject decorative grid wallpaper, default line backgrounds, calibration-mark wallpaper, soft glow backgrounds, generic abstract marks, testing/demo/placeholder UI copy, terminal-only user flows, and first-output composition with only local copy swapped in when they have no product function. Treat measurement, calibration, crop, route, timeline, and inspection marks as task overlays or control affordances only; never promote them to the page background, hero backdrop, or first-output visual texture. If a conceptual anchor suggests a forbidden motif, the forbidden motif wins; express the anchor through workflow, hierarchy, density, typography, material behavior, state design, and interaction grammar instead of literal wallpaper.
-## Pre-Emit Identity Check
-
-Before outputting any UI code, mockup, or design direction, answer:
-
-1. **Specificity test**: If the product name and all text were removed from this UI, would a designer still identify what product category and what specific product this was built for? If the answer is "no" or "only category, not this specific product" -- revise the concept, not the details.
-
-2. **Structural variety test**: Does the hero or primary viewport avoid the centred-everything composition (large name centered, subtitle below, CTA below that)? If yes, pass. If no, name the product reason for centred composition or revise.
-
-3. **Default detection test**: Name the one design default you were most tempted to use. Confirm it was rejected or adapted with a product-specific reason, not merely avoided.
-
-Failure on any test requires revision before output. This check is not optional and applies to both new designs and additive UI tasks that change composition.
-
-## Brave Redesign Default
-For UI design work, the agent owns the ambition decision. For broad screens, redesigns, or new visual systems, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich". Do not reduce the request to a safer version of the existing UI, a static implementation, or a component-kit rearrangement because research or dependency selection feels inconvenient.
-
-If the expressive path needs a new motion, 3D, canvas, scroll, or interaction library and web search is available, perform the official-doc research and record the decision. If web search is unavailable, use already-present dependencies or native browser capabilities while preserving the intended ambition, then mark library verification as pending.
-
-Only downshift ambition after naming the concrete blocker: product fit, content density, measured performance budget, accessibility, device support, package conflict, security risk, or missing runtime capability. A new dependency, package count, or vague performance concern is not a blocker by itself. Pair every downshift with a replacement interaction quality that still changes composition, hierarchy, feedback, or memorability.
-## Design Flexibility Layer
-`docs/design-intent.json` must separate locked outcomes from flexible expression. The machine contract keeps review invariants stable; it must not freeze exact aesthetic implementation unless repo evidence, accessibility validation, implementation constraints, or explicit user approval locks it. Record `designFlexibilityPolicy`: lock user goals, runtime constraints, accessibility, production readiness, forbidden patterns, and approved continuity; keep exact palette primitives, font families, radius/shadow values, component-kit theme mapping, signature move implementation, literal anchor artifacts, and spatial metaphors flexible until validated or approved. Semantic roles are required; exact primitives are not automatically locked.
-## External Inspiration Boundary
-Using outside websites, benchmark apps, galleries, or component examples is useful for constraint discovery, interaction mechanics, and implementation options, but never as a style source to imitate. Extract why a pattern works, then translate it into a current-project rule. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture from a reference unless the user explicitly approves that continuity and it passes product fit.
-
-## Adaptive Research Freshness
-Modern is relative to the current date, not a fixed release year: implementation/platform claims require current official docs or primary release notes; trend, category-code, and visual-language claims prefer sources published or materially updated within the last 24 months; older sources must be labeled `old-timeless` and cannot prove a current-year trend.
-User-provided concepts are first-class constraints; adapt research to support, refine, or challenge the concept, and if live research is unavailable set source freshness to pending verification instead of claiming current-year modernity.
-
-## AI Color and Template Residue Audit
-AI color drift happens when a palette uses safe defaults before product meaning.
-
-Complete the AI color audit before coding:
-- Explain what product evidence or anchorReference makes the palette fit.
-- Name the color roles that carry task, status, data, or navigation meaning.
-- Name one color behavior that would not transfer cleanly to another product category.
-- Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.
-
-Cream, slate, monochrome, purple-blue gradients, cyber-neon terminals, pale editorial surfaces, soft glow atmospheres, and dark control rooms are autopilot risks, not banned palettes.
-
-## Motion and 3D Courage Rule
-Motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries are first-class UI options when they improve understanding, exploration, feedback, hierarchy, memorability, or confidence.
-
-Use modern, expressive interaction when it improves hierarchy, feedback, confidence, or memorability.
-
-If rich motion or spatial UI is omitted, record the product, content-density, performance, accessibility, or device reason and the replacement interaction quality. "Not necessary" is not enough.
-
-If 3D or canvas is used, record product role, interaction model, fallback path, runtime/library choice, loading state, keyboard path, and reduced-motion behavior.
-
-## Token Derivation Audit
-Before implementation, `docs/design-intent.json` must include top-level `derivedTokenLogic`: `anchorReference`, `colorDerivationSource`, `spacingDerivationSource`, `typographyDerivationSource`, `motionDerivationSource`, `colorSpace`, `spatialBaseUnit`, `typeScaleMethod`, `motionBudget`, and `validationRule`.
-
-Every semantic token role must trace to `anchorReference`. Exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them. If the rationale is "looks good", "common practice", "modern default", or "framework default", derive the token again before UI code.
-
-## Implementation Craft Layer
-Before accepting the design contract, record explicit CSS craft decisions:
-- Color: prefer OKLCH tokens and tinted neutrals for new CSS when supported, preserve existing token formats, name color commitment level, derive scales as a perceptual lightness curve (not linear) with semantic role layers (surface, foreground, border, focus, status, data) before primary/secondary/accent, record one accessible text-on-color pair per interactive step, and treat dark mode as a second derived palette with its own lightness curve; record `color-scheme`, prefer `light-dark()` for theme-switch tokens, and record the no-flash and persistence strategy.
-- Typography: prefer fluid `clamp()` scales with explicit role contrast, `text-wrap: balance`, and numeric typography decisions; treat type as a system rather than a font choice, recording one variable-axis decision (`wght`/`wdth`/`opsz` when available), one `font-feature-settings` choice tied to product role (tabular numerals for data, stylistic alternates or `case` for editorial voice), one measure (line-length budget), and an FOUT/FOIT strategy with `font-display` plus metric override when web fonts are loaded.
-- Spatial/motion: name `spatialBaseUnit`, major multiples, optical exceptions, and `motionBudget`; prefer transform/opacity choreography, explicit easing, bounded stagger, and reduced-motion behavior.
-- Implementation anti-attractor: list three default CSS reflexes this task might trigger, reject the most likely one, and choose one distinctive implementation move tied to the product.
-
-## Library Research Protocol
-If web search is available:
-- Verify each new UI-related library against current official docs.
-- Record source URL, fetched date, stable compatible version, purpose, risk, and fallback in `libraryDecisions[]`.
-- Set `libraryResearchStatus` to `verified` only when every external library decision has evidence.
-
-If web search is unavailable:
-- Do not hallucinate package names, APIs, versions, or imports.
-- Use native CSS, browser APIs, or already-present dependencies.
-- Set `libraryResearchStatus` to `pending-verification`.
-
-Treat unresearched dependency choices as review findings. Dynamic UI Foundation Selection: do not default to shadcn/ui, Tailwind-only, native-only, or any component kit because it is familiar, and do not avoid them because a guardrail exists. Choose the foundation from product type, interaction complexity, accessibility needs, design ambition, team/runtime constraints, bundle/runtime cost, and current official docs.
-Ready-made primitives are allowed when they improve behavior, accessibility, speed, or maintainability. The library supplies mechanics; the project supplies visual language. Reject default component-kit styling without product rationale, but do not reject a modern lightweight library solely because a dependency was needed.
-
-Tailwind-first is valid only as an implementation fit, not as ideology or anti-ideology. Use Tailwind utilities and CSS-first tokens when they fit the chosen stack and team, but do not make pure Tailwind, vanilla CSS, shadcn/ui, or any component kit the default answer when product evidence points to stronger primitives, charts, motion, gestures, canvas, or framework tooling.
-
-For fresh projects, prefer official framework scaffolders or setup commands when current official docs show they create the supported project shape. Manual from-scratch file assembly is acceptable for tiny prototypes, educational exercises, repo-specific constraints, or when official scaffolders cannot satisfy the approved architecture; document that reason.
-## Zero-Based Redesign Protocol
-
-When the user says "redesign from zero", "redesain dari 0", "ulang dari 0", or "research ulang":
-- Treat existing UI as content, behavior, accessibility, and asset evidence only.
-- Rewrite or materially update both design docs before UI code.
-- Add `visualResetStrategy`.
-- Reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.
-- Do not ship a palette swap, dark-mode flip, or same hero with new colors.
-- Run the redesign regression test: if the result preserves the old hero structure, navigation grammar, card rhythm, motion density, image framing, or primary interaction model without explicit user-approved continuity, revise before implementation is considered complete.
-
-## Responsive Recomposition Plan
-
-Responsive design means recomposition, not resizing.
-
-Define viewport mutation rules:
-- Mobile: prioritize the first decisive action and touch flow.
-- Tablet: regroup surfaces without becoming a shrunken desktop.
-- Desktop: expose more context without defaulting to admin chrome.
-- For each viewport, name what is reordered, merged, hidden, disclosed, promoted, and forbidden.
+## Step 1: Name Your Defaults
+
+Before any visual choice, name three design directions you are most tempted to use for this project. For each:
+1. Name the specific visual pattern (layout, palette, density, motion, typography).
+2. Argue against it: why would it flatten what is specific about THIS product's core purpose and data shape?
+3. Derive your search direction from the rejection argument.
+
+## Step 2: Choose an Anchor
+
+Pick one concrete, googleable real-world reference whose interaction mechanics (not surface styling) translate to this UI. The anchor must be specific enough that renaming the product to a different category breaks coherence.
+
+Hard constraints:
+- Reject generic quality words as anchors: "modern", "clean", "premium", "minimal", "bold" are not anchors.
+- Do not default to spatial place metaphors (room, studio, lab, cockpit, command center). Prefer artifacts, workflows, instruments, data behaviors, or interaction mechanisms.
+- Record what mechanic is borrowed and what is explicitly NOT borrowed (palette, component skin, layout rhythm).
+
+## Step 3: Creative Commitments
+
+Record before coding:
+1. **Typography**: Choose distinctive fonts with meaningful role contrast. Avoid Inter, Roboto, Arial, Space Grotesk, system fonts.
+2. **Color and palette**: Dominant colors with sharp accents. Name what product evidence makes the palette fit. Name one color behavior that would not transfer to another category.
+3. **Motion and interaction**: Define one signature motion behavior more specific than "smooth." One well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
+4. **Composition**: One composition choice that avoids interchangeable card stacks. Create atmosphere and depth rather than solid backgrounds.
+
+## Previous Directions (do not repeat)
+
+If `docs/DESIGN.md` contains a list of previous directions, treat every entry as a blocklist. The chosen anchor must differ from every blocklisted entry on conceptual family, hierarchy, and motion. Restating an existing direction with new wording is not a new direction.
+
+## Named Defaults to Avoid
+
+- `dev-tool default`: condensed tabular numerics, monospace on dark slate, monochrome status dots, minimal chrome
+- `AI-startup landing default`: purple-to-pink gradient hero, floating glass cards, three-up feature grid, vague hero copy
+- `SaaS admin default`: left-side icon-only nav, top utility bar, three-card KPI row above data table, neutral grey
+- `marketing site default`: hero image with headline, three feature tiles, pricing tiers, testimonial carousel
+
+Avoid: purple gradients on white, predictable centered-everything composition, solid-color backgrounds without depth, cookie-cutter component patterns. Never converge on common choices across generations.
+
+## Post-Implementation Check
+
+After generating UI code, answer:
+1. If the product name were removed, would a designer identify what specific product this was built for? If no, revise the concept.
+2. Does the primary viewport avoid the centered-everything default? If no, name the product reason or revise.
+3. Name the one default you were most tempted to use. Confirm it was rejected with a product-specific reason.
+
+## Redesign Protocol
+
+When the user says "redesign from zero" or equivalent: treat existing UI as behavioral evidence only. Rewrite design docs. Change primary composition, hierarchy, interaction model, and responsive architecture. Do not ship a palette swap or same hero with new colors.
 
-## Required `docs/DESIGN.md` Sections
-1. Design Intent and Product Personality
-2. Audience and Use-Context Signals
-3. Visual Direction and Distinctive Moves
-4. Color, Typography, Spacing, and Density Decisions
-5. Token Architecture and Alias Strategy
-6. Responsive Recomposition Plan
-7. Motion, Interaction, and Feedback Rules
-8. Component Language, States, and Morphology
-9. Source Boundaries and Context Hygiene
-10. Accessibility Non-Negotiables
-11. Anti-Patterns to Avoid
-12. Implementation Notes for Future UI Tasks
+## Required Docs
 
-## Required `docs/design-intent.json` Behavior
-
-The JSON is the source of truth for machine review. It must stay project-specific and include:
-- confirmed project context and assumptions
-- agent-chosen visual direction
-- `motionPaletteDecision`
-- `designFlexibilityPolicy`
-- `conceptualAnchor`
-- `derivedTokenLogic`
-- `aiSafeUiAudit` and `productionContentPolicy`
-- `tokenSystem`, `colorTruth`, `crossViewportAdaptation`, `motionSystem`, and `componentMorphology`
-- `accessibilityPolicy`
-- `designExecutionPolicy`
-- `designExecutionHandoff`
-- `reviewRubric`
-- `contextHygiene`
-- `libraryResearchStatus` and `libraryDecisions[]`
-- `forbiddenPatterns`
-- `repoEvidence.designEvidenceSummary` when available
-
-## Accessibility and Review
-
-WCAG 2.2 AA is the hard floor. APCA may be used only as advisory perceptual tuning.
-
-Define a review rubric that names drift signals and separates taste from failure.
-
-Block or flag inaccessible contrast/focus/target/keyboard/auth/status behavior, scale-only responsive behavior, default component-kit styling, nonfunctional background effects, grid or line filler, placeholder copy, terminal-only core flows, readability-as-safe-default palettes, copied visual direction, and genericity findings that cannot name the exact drift signal.
-
-Wait for user approval before generating Figma or code assets when the user only asked for planning or design direction.
+Generate or refine `docs/DESIGN.md` (human-readable design direction) and `docs/design-intent.json` (machine-readable intent with `conceptualAnchor`, creative commitments, and anti-repeat ledger) before UI implementation.

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

@@ -3,131 +3,22 @@ id_prefix: API
 domain: api-docs
 priority: high
 scope: backend
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - api-docs
-  - api
-  - contract
-  - documentation
-  - readme
-  - writing
+applies_to: [backend, fullstack]
+keywords: [api-docs, api, contract, documentation]
 ---
 
-# API and Public Contract Boundary
-
-## API-001: Documentation as Hard Rule (Boundary-Aware)
-
-1. If a change affects an API, CLI command, exported library behavior, schema, event, or integration contract, update the matching docs in the same change.
-
-## API-002: Public README Boundary
-
-1. Root `README.md` is required for every fresh or existing project, including private projects, because a future maintainer still needs a clear public and developer entrypoint.
-2. README content must be safe for outside readers and useful for developers.
-3. README content must explain what the project is, who it is for, how to set it up, how to run the main workflow, how to configure it, and where deeper docs live when those topics apply.
-4. Keep README overview-level. Do not make it the canonical governance source. Do not put secrets, private agent notes, hidden reasoning, backlog chatter, raw architecture debate, or internal policy dumps in it.
-5. Choose README sections from project evidence. Do not force a fixed template when a section does not apply.
-6. For private/internal projects, keep the same clear style but omit private URLs, credentials, customer names, and internal-only operational details that do not belong in repo docs.
-
-## API-003: Documentation Growth Model
-
-1. Documentation must evolve with the project.
-2. When behavior, setup, architecture, public contracts, data shape, deployment, or validation changes, update README and the matching docs in the same change.
-3. When `docs/` exists, keep `docs/doc-index.md` as the compact routing map for humans and agents. It should list active docs, their purpose, read triggers, status, and last update.
-4. `docs/doc-index.md` must not duplicate requirements, architecture, or API contracts.
-5. Start compact, then split only when a topic earns its own file.
-6. Good split signals are: the section is long, the workflow is owned separately, the content is referenced often, or the topic needs step-by-step care such as hardware setup, deployment, testing validation, operations, or troubleshooting.
-7. Use PRD, SRS, technical design, and ERD as conditional docs, not default boilerplate. PRD covers product intent and roadmap ownership; SRS covers contractual or complex acceptance criteria; technical design covers architecture under pressure; ERD stays inside `docs/database-schema.md` unless the data model is large or relationship-heavy.
-
-## API-004: Public Contract Rules
-
-1. Document the public surface before or alongside implementation.
-2. Machine-readable API contracts should use the current project standard. If unresolved, the LLM must recommend a current maintained option from official docs.
-3. HTTP APIs should prefer OpenAPI 3.1 when no stronger project standard exists.
-4. Choose transport (REST, GraphQL, tRPC, gRPC, SSE, WebSocket) and shape (resource-oriented vs action/command-oriented) from domain evidence, not by habit.
-5. When the domain has verbs such as cancel, refund, dispatch, approve, or retry, prefer command endpoints over awkward `PATCH` shoehorns and record at least one alternative transport considered.
-6. Treat HTTP as a behavioral contract, not just a shape.
-7. Document `ETag` and conditional requests for cacheable reads, `Cache-Control` and `Vary` when shared caches apply, rate-limit headers (`RateLimit-*` or `X-RateLimit-*`) with `Retry-After` when rate limiting exists, and require an `Idempotency-Key` request header on unsafe non-idempotent mutations.
-8. List endpoints must document pagination, limits, filtering, sorting, and empty-state behavior.
-
-## API-005: Boundary Contract Details
-
-1. Sensitive mutation endpoints must document idempotency behavior, retry safety, duplicate-submit handling, and any required idempotency key or request fingerprint.
-2. Public error contracts must document stable machine-readable codes and any RFC 9457 Problem Details-style fields the project exposes, including safe trace or correlation identifiers when present.
-3. Async, webhook, and event contracts must document idempotency, retry, ordering, dead-letter or recovery behavior, and duplicate-message handling.
-4. Event APIs should define producer, consumer, payload, versioning, retry, and failure behavior.
-5. CLI/library public behavior must update README, help text, changelog, or docs as appropriate.
-6. Do not write "see code" as the contract.
-7. Do not expose generic `object` or `any` contract shapes when the boundary can be typed.
-8. Public error shapes must be safe, stable, and documented.
-9. Versioning, deprecation, and support-window obligations for any public surface live in `api-versioning.md`; load it together with this rule when authoring or reviewing a versioned contract change [REF:VER-001].
-
-## API-006: Human Writing Standard (Mandatory)
-
-1. This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.
-2. API docs and README updates are included in this scope.
-3. Write formal project docs in English by default, even when the user prompt is in another language.
-4. Use another documentation language only when the user explicitly asks for it or when existing project docs already establish that language.
-
-## API-007: Style Baseline
-
-1. Write for native English speakers.
-2. Target an 8th-grade reading level.
-3. Use clear, direct, plain language.
-4. Keep sentence rhythm natural with short and medium sentences.
-5. Sound confident, practical, and conversational.
-6. State the main point first, then supporting detail.
-
-## API-008: Required Writing Behavior
-
-1. Explain decisions the way a competent coworker would explain them out loud.
-2. Cut unnecessary words and remove filler.
-3. Use concrete verbs and everyday phrasing.
-4. Rewrite and reorder content when flow is weak.
-5. Keep explanations short by default; expand only when complexity requires it.
-
-## API-009: Scope Severity and Merge Behavior
-
-1. Scope style guidance controls readability and consistency.
-2. Style baseline findings are advisory by default and must not block endpoint-change commits that already include accurate docs/spec updates.
-3. Hard blockers remain contract failures: missing same-commit docs sync, incorrect schema, missing required responses, or factual inaccuracies.
-4. If style polish is still needed, open a follow-up task instead of delaying the contract update.
-
-## API-010: Non-Negotiables
-
-1. No emoji in formal artifacts.
-2. Avoid AI cliches and buzzwords: delve, leverage, robust, utilize, seamless.
-3. Avoid inflated, academic, or performative language.
-4. Avoid padding, hedging, and redundant phrasing.
-
-## API-011: Critical Controls and Final Check
-
-1. Any claim about quality, performance, or reliability must include a measurable source and timestamp.
-2. Expand acronyms on first use, then use terms consistently.
-3. Separate facts from assumptions explicitly.
-4. End major explanations with a clear next action.
-5. Read the text out loud before shipping. If it sounds robotic, rewrite it.
-
-## API-012: Idempotency as Runtime Invariant
-
-1. Side-effect-producing endpoints (a `POST` that creates a resource, a `PUT` or `PATCH` that mutates a resource, a request that issues a charge, a request that triggers a downstream notification) must accept an idempotency identifier on retry. The identifier is a caller-supplied key on each logical attempt; the producer commits the effect once and stores enough state to recognize the same key.
-2. The server must return the original response on duplicate submissions of the same idempotency identifier within a documented retention window. The retention window must be long enough to cover the platform's worst-case retry interval (network retry plus client-side retry plus operator-driven replay) and is recorded in the API contract per endpoint, not picked at random per call site.
-3. The idempotency identifier scope must be documented: per caller, per resource, per tenant, or globally. A scope mismatch (one tenant's key colliding with another's) is a data-leak bug, not a load-balancing edge case.
-4. The contract must distinguish three duplicate outcomes: replay-of-same-success (return the original 2xx response unchanged), replay-after-permanent-failure (return the original 4xx response unchanged), and replay-with-different-payload-under-same-key (reject with a clear error so the caller does not silently overwrite the recorded result with a new request body).
-5. Storage for idempotency state must be durable across process restarts; in-memory caches are not sufficient on multi-instance deployments. The store may be the same database, a separate key-value store, or a platform-equivalent dedup layer, provided durability and lookup latency are recorded.
-6. Reject "the database's primary-key constraint will catch duplicates" as a substitute for an idempotency layer; primary-key collisions surface as 5xx-shaped errors that callers retry, which makes the problem worse.
-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.
+# API Contract Boundary
+
+## API-001: Execution Rules
+1. Sync docs in the same commit when changing API, CLI, or schema.
+2. Root README.md is mandatory. Keep it overview-level. No secrets.
+3. Keep `docs/doc-index.md` as the routing map.
+4. Use OpenAPI 3.1 for HTTP APIs by default.
+5. Idempotency is mandatory for side-effect mutations (POST/PUT/PATCH).
+6. Use Mermaid.js natively for all diagrams. No PlantUML/D2.
+
+## API-002: Human Writing & Anti-Slop (Mandatory)
+1. NO EMOJI in any formal documentation, code, or review summaries. This is absolute.
+2. Use plain English and avoid generic AI cliches ("AI slop") in generated docs.
+3. Keep code clean and efficient. Do not write convoluted/long code if a shorter, efficient solution exists without losing functionality.
+4. Keep documentation short, clear, and directly actionable.

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

@@ -1,93 +1,16 @@
 ---
 id_prefix: VER
 domain: api-versioning
-priority: high
-scope: api
-last_validated: 2026-05-17
-applies_to:
-  - backend
-  - fullstack
-keywords:
-  - api-versioning
-  - deprecation
-  - breaking-changes
-  - support-window
-  - sunset
-  - migration
+priority: medium
+scope: backend
+applies_to: [backend, fullstack]
+keywords: [api-versioning, versioning, deprecation]
 ---
 
 # API Versioning Boundary
 
-A public API surface is a contract with callers the producer does not control. Versioning safety is the property that the producer can evolve the contract without silently breaking those callers, and that callers can recognize and respond to evolution before it forces an outage. Vendor names that may appear in commentary (API gateways, contract registries, deprecation-tracking platforms) are not authority for this rule.
-
-## VER-001: Single versioning strategy per surface (Mandatory)
-
-1. Each public API surface (a service's HTTP endpoints, a service's RPC methods, a published event schema, a CLI's command shape, a published SDK) must adopt one versioning strategy and apply it consistently. Acceptable strategies include URL-path versioning, header-based versioning, content-negotiation, schema-driven versioning where the schema carries the version, and date-based versioning. The choice belongs to the surface, not to the developer of the moment.
-2. Reject mixed strategies on the same surface (path-versioned for some endpoints and header-versioned for others; date-versioned for queries and unversioned for mutations). The mix forces every caller to learn two rules where one is sufficient.
-3. The strategy and its current supported version range must be documented in the surface's contract documentation, not inferred from example URLs or sample headers.
-
-## VER-002: Define breaking and non-breaking changes (Mandatory)
-
-1. The following are breaking changes regardless of strategy:
-   - Removing or renaming a request field, a response field, an endpoint, an RPC method, an event type, or a CLI command.
-   - Tightening request validation (a value previously accepted is now rejected; a previously optional field is now required).
-   - Changing the default value or default behavior of an existing field, parameter, or operation.
-   - Changing the type, units, encoding, or semantic meaning of an existing field.
-   - Changing the documented error semantics (status code, error code, or error shape) of an existing endpoint.
-2. The following are non-breaking changes:
-   - Adding a new optional request field with a documented default behavior when the field is absent.
-   - Adding a new response field that older clients can ignore, on a surface whose contract permits unknown fields (most modern HTTP and event surfaces do; verify per surface).
-   - Adding a new endpoint, RPC method, event type, or CLI command.
-   - Adding a new optional header with a documented absent-default.
-3. Any change that is breaking by the definition above must use the surface's versioning strategy or wait for the next major version. Reject silent breaking changes (a field type narrowed without a version bump; a status code changed without a version bump).
-
-## VER-003: Deprecation discipline (Mandatory)
-
-1. A deprecation announces, while the deprecated path is still functional, that callers must migrate. Deprecation must include all of the following before the deprecated path can be removed:
-   - A documented sunset date or replacement-criterion that callers can plan against.
-   - In-band signaling on the deprecated path, using the platform's standardized mechanism where one exists. For HTTP surfaces, RFC 9745 (the `Deprecation` header) and RFC 8594 (the `Sunset` header) are the current standardized mechanisms; signal with both where the platform and clients support them, and document the in-band signal in the contract documentation. Adoption of these specifications is uneven, so out-of-band communication is acceptable when the in-band channel is unavailable, provided the out-of-band path is documented and reaches affected callers.
-   - A migration guide published in the same release that begins deprecation, that names the replacement and shows at least one example transformation per use case the deprecated path supported.
-   - Telemetry that tracks remaining traffic on the deprecated path, broken down by caller identity where the surface supports identifying callers, so the producer knows when removal is safe.
-2. Reject silent removal of an endpoint, field, or method that has not gone through deprecation. "We checked our analytics and nobody used it" is not deprecation; it is an unannounced breaking change with extra steps.
-3. The sunset date must respect the surface's documented support window (VER-004); a sunset announced today and effective tomorrow is not a sunset, it is a removal.
-
-## VER-004: Support windows (Mandatory)
-
-1. Each public API surface must publish an explicit support window: how long after a new major version ships will the previous major version continue to receive bug fixes, security fixes, and uptime guarantees. The window must be expressed in calendar time (months or years), not in subjective terms.
-2. The producer must continue to operate prior versions within the support window even when the producer prefers callers had migrated. Removing a still-supported version is a breach of the published contract.
-3. End-of-life must be announced before the support window expires, with sufficient lead time for callers to migrate. The lead time required depends on the caller population (an internal service may migrate in a sprint; a public SDK with mobile-app callers may need a year because of app-store update cycles); the producer must document the assumption.
-4. Reject "we will remove it when we feel like it" as a support policy. Reject removing an endpoint, field, or method while it is still inside its published support window.
-
-## VER-005: Additive evolution as default (Mandatory)
-
-1. The default response to a feature request that touches an existing surface is to evolve additively: add a new optional field, a new endpoint, a new optional behavior triggered by an explicit opt-in. Reach for a new major version only when additive evolution costs more than client migration would cost (a fundamental shape change, a security correction that cannot coexist with the old shape, a deprecated dependency removal that callers must follow).
-2. A new major version is itself a contract that incurs all of VER-001, VER-002, VER-003, and VER-004; it is not a license to ship unannounced breaking changes under a new path.
-3. Reject `/v2/` (or platform-equivalent) path forks that duplicate the previous version's codebase without a deprecation telemetry plan, a sunset date for the prior version, and a migration guide. A new path without these is two codebases the producer must maintain in parallel forever.
-4. The producer must not run a `/v1/` and a `/v2/` indefinitely on the same surface in the absence of a sunset plan; that pattern doubles operational cost and dilutes the contract.
-
-## VER-006: Compatibility testing (Mandatory)
-
-1. Every release that touches a public surface must run a compatibility check against the surface's previous supported versions: previously valid requests still validate, previously valid responses still parse against published schemas, previously documented error shapes still surface for the same error conditions.
-2. The compatibility check must run in CI, not as a manual pre-release step. Reject "we test compatibility manually before release"; manual compatibility checks miss regressions in less-trafficked endpoints.
-3. The compatibility check's failure must block the release, not file a follow-up ticket.
-
-## VER-007: Reject these bad habits
-
-1. Reject changes that are breaking by VER-002 but ship without a version bump or a deprecation cycle.
-2. Reject deprecation banners in release notes that have no in-band signal on the deprecated path.
-3. Reject sunset dates that are not enforced; a producer who keeps the deprecated path alive past sunset trains callers to ignore future sunsets.
-4. Reject `/v2/` forks of an existing surface that the producer cannot show a migration plan for.
-5. Reject contract documentation that lists endpoints without naming the version they belong to.
-
-## VER-008: Citations and freshness
-
-Authority sources for the rules in this file:
-
-- IETF RFC 9745: standardized HTTP `Deprecation` response header for in-band deprecation signaling. Adoption is uneven across clients and intermediaries, so pair with out-of-band documentation.
-- IETF RFC 8594: standardized HTTP `Sunset` response header for in-band sunset-date signaling. Same adoption caveat as RFC 9745.
-- IETF RFC 9457: problem-detail responses for HTTP errors; authority for keeping error semantics stable across versions.
-- OpenAPI Specification (current major version): authority for declaring HTTP surface versioning in machine-readable form when the surface uses HTTP.
-- AsyncAPI Specification (current major version): authority for declaring event-driven surface versioning when the surface publishes events.
-
-Vendor-specific API gateways, contract registries, and deprecation-tracking platforms are illustrative implementations of the rules above; they are not authority. The mechanism is platform-specific; the contract obligations above are not.
-<!-- DURABILITY CHECK: Rule relies exclusively on architectural invariants and relative operational thresholds. Valid beyond standard tooling lifecycles. -->
+## VER-001: Execution Rules
+1. Never introduce breaking changes without versioning.
+2. Maintain backward compatibility.
+3. Use header-based or URL-path versioning explicitly.
+4. Document deprecation windows before sunsetting endpoints.