@ryuenn3123/agentic-senior-core 4.0.0 → 4.0.1

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

@@ -13,12 +13,14 @@ This contract is a decision scaffold, not a style preset. We guide the agent; we
 - Keep external references non-copying; extract constraints only.
 - Before choosing a new UI, animation, scroll, 3D, canvas, chart, icon, styling, or component library, research current official docs.
 ## Required Order
-1. Read `AGENTS.md`, this prompt, `../rules/frontend-architecture.md`, current UI code, current project docs, and existing design docs.
+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-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).
+8. 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`.
 ## 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

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

@@ -0,0 +1,165 @@
+---
+inclusion: manual
+---
+
+# Research-Design Brief
+
+Authoritative design-research execution contract for UI scope. Loaded by UI Design Mode after `bootstrap-design.md`. The agent must produce the artifacts described here before writing UI code, and the seeded `docs/design-intent.json` must contain the fields named in Section 5.
+
+This brief is a single document with five sections. Sections 1 and 2 set up the research. Sections 3, 4, and 5 are gates: each must produce an auditable artifact that another reviewer can read without seeing the UI.
+
+## Authority
+
+- Treat `.agent-context/` and current project docs as technical authority.
+- Treat `README.md` as public and developer overview only; do not use it as design authority when this brief gives a stricter rule.
+- Treat external websites, benchmark apps, prior chats, and unrelated-project memory as candidate evidence for constraints, mechanics, and quality bars only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
+- WCAG 2.2 AA is the hard compliance floor. APCA may be used only as advisory perceptual tuning.
+
+## Anti-Repeat Ledger Gate (read first)
+
+If `docs/design-intent.json` already exists and carries `researchDossier.metadata.antiRepeatLedger`, treat every entry under `previousAnchors`, `previousPalettes`, and `previousMotionSignatures` as a hard blocklist before producing any candidate in Sections 3-5.
+
+Rules:
+
+- 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, not pass.
+- A user-explicit redesign request ("redesign from zero", "redesain dari 0", "ulang dari 0", "research ulang", or any explicit reset) bypasses the freshness gate but does not weaken the ledger; previously shipped direction stays blocklisted unless the user explicitly says "revive existing direction".
+- Ledger entries are signature-level descriptors, not raw token dumps; treat them as direction summaries.
+
+If the ledger is empty or `researchDossier.metadata.researchVerifiedAt` is null because the contract is a fresh seed, the ledger is informational only and does not add blocklist entries.
+
+## Section 1 — Product Reading
+
+Before any visual choice, write a structured product reading:
+
+- Product type and core verb (what the user does, not what the UI shows).
+- Three highest-stakes user moments, ordered by frequency.
+- Data shapes that dominate the screen (timeseries, ledger, list, document, control, telemetry, conversational, spatial, other).
+- Latency profile (real-time, soft real-time, batch, ambient).
+- Failure modes the UI must absorb visibly (partial, stale, optimistic, conflict, offline, permission, rate-limit, none).
+- Context of use (one-shot, sustained focus, glance-and-go, background monitor, shared display, embedded).
+- Known constraints (device, runtime, accessibility, regulatory, performance budget, brand continuity).
+
+Output: `productReading` block. Each field must be one sentence, evidence-backed from repo or brief. Speculation is not allowed; if a field is unknown, name it as such and stop until the user resolves it.
+
+## Section 2 — Reference Intake
+
+Reference material is fuel for variance, not a style source.
+
+- Capture between three and seven references per dimension that needs exploration: hierarchy, density, type system, motion, state language, material logic, color behavior.
+- For each reference, record: source URL or citation, what is borrowed (mechanic, behavior, hierarchy, density, type pairing, motion choreography), and what is explicitly not borrowed (palette, component skin, layout rhythm, brand posture).
+- References live in `referenceIntake[]`. The agent may not select an anchor in Section 5 that copies a reference's surface; only the borrowed mechanic is allowed to flow downstream.
+
+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
+
+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.
+
+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.
+
+Fails specificity:
+- `clean typography` (too abstract, applies to anything)
+- `modern color palette` (not falsifiable)
+- `smooth animations` (describes nothing specific)
+
+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.
+
+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`
+- `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.
+
+## 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.
+
+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` }).
+
+## Section 5 — Anchor Candidates
+
+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.
+
+Hard constraints on anchors:
+- The anchor must be concrete and googleable. "Modern", "clean", "premium", "expressive", "minimal", "bold", "futuristic", "elegant" are not anchors.
+- 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).
+
+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.
+
+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.
+
+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.
+
+For EACH of the five candidates, record:
+
+- `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
+
+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).
+
+## Done Criteria
+
+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`.
+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/AGENTS.md

@@ -73,9 +73,10 @@ Load the matching prompt only:
 - `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
+- `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.
 
-For UI-only work, load `bootstrap-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.
+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.
 
 ### Layer 6: Governance Modes
 
@@ -135,14 +136,14 @@ Load `pr-checklist.md` and `architecture-review.md`, then report defects, risks,
 
 Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
 
-1. Read `bootstrap-design.md` and `frontend-architecture.md`.
-2. Read UI-relevant repo evidence from state, current UI code, and `docs/*`.
-3. Include a one-line Motion/Palette Decision before UI code; product categories are heuristics, not style presets.
-4. Before UI code, record one real-world anchor, one signature motion behavior, and one typographic role contrast.
-5. Ensure `docs/design-intent.json` includes `conceptualAnchor.anchorReference`, top-level `derivedTokenLogic`, `libraryResearchStatus`, `libraryDecisions[]`, and motion/palette decisions.
-6. Generate or refine `docs/DESIGN.md` plus `docs/design-intent.json` before UI implementation.
-7. Keep context isolated; do not eagerly load unrelated backend-only rules.
-8. In UI Design Mode, choose the ambition level proactively. For broad screens or redesigns, treat expressive motion, spatial hierarchy, distinctive composition, and product-specific interaction as the baseline even when the user did not say "rich"; quiet or static surfaces require a concrete product, performance, accessibility, device, or dependency reason.
+1. Read `bootstrap-design.md`, `research-design.md`, and `frontend-architecture.md`. Read UI-relevant repo evidence from state, current UI code, and `docs/*`.
+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.
+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.
 9. Do not let conceptual anchors collapse into room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center by habit. Prefer artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms unless a physical place model is core to the product.
 10. External websites and benchmark examples are candidate evidence for constraints, mechanics, and quality bars only. Do not copy their layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
 
@@ -176,4 +177,4 @@ Verify reachability when relevant: Layer 1 Rules, Layer 2 Runtime Decision Signa
 - Before PR: run review checklists.
 - Before deploy: check policy thresholds.
 - Before major refactor: read `architecture-map.md`.
-- Before UI implementation: confirm valid style context, design contract, and required docs.
+- Before UI implementation: confirm valid style context, design contract, and required docs.

package/README.md

@@ -27,7 +27,7 @@ Highlights:
 The internal `.agent-context/rules/` pack is now numbered Markdown with YAML frontmatter and stable section IDs (e.g. `FE-004`, `ARCH-009`, `API-006`). This is a breaking change for downstream consumers that parse rule headings; the migration guide lives in `CHANGELOG.md` under `4.0.0`. Repository-wide impact:
 
 - Rules are now citable by ID, which the new bounded reflection block in `AGENTS.md` and the validation MCP tools (`lookup_rule`, `validate_against_rules`, `audit_compliance`) rely on.
-- A three-layer prompt caching contract (D4 in `docs/plan/research-foundation.md`) is now enforced by `npm run audit:cache-layer-contract`.
+- A three-layer prompt caching contract (D4 in `docs/architecture/decisions-foundation.md`) is now enforced by `npm run audit:cache-layer-contract`.
 - A provider-free anti-halu benchmark is included (`benchmarks/anti-halu/`); pass rate and citation validity are reproducible locally.
 - Caching numbers are scoped per integration. The 89.31% Anthropic warm-cache effective reduction reported in `benchmarks/results/cache-phase-2-2026-05-16.json` applies to direct provider API and Claude Code SDK programmatic mode only. IDE wrapper integrations (Cursor, Windsurf, Codex CLI, Kiro) receive prefix stability without a measurable per-pack saving. See `docs/integration-playbook.md` for the per-tool matrix and `docs/benchmark-reference.md` for the required reporting JSON shape.
 

package/lib/cli/commands/init.mjs

@@ -54,6 +54,7 @@ import {
   loadProjectConfig,
   normalizeDocsLanguage,
 } from '../project-scaffolder.mjs';
+import { migrateExistingDesignIntentToResearchDossierSchema } from '../project-scaffolder/design-contract/research-dossier-migration.mjs';
 import { performRollback } from '../rollback.mjs';
 import {
   createTokenOptimizationState,
@@ -483,6 +484,16 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       supplementalMaterializedDocFileNames.push('design-intent.json');
 
       console.log('\nExisting UI/frontend scope detected. Seeded docs/design-intent.json so the machine-readable design contract exists before UI implementation work continues.');
+    } else if (projectDetection.hasExistingProjectFiles && (await pathExists(designIntentTargetPath))) {
+      // Scenario E: existing project being initialized for the first time
+      // already has docs/design-intent.json. Migrate it to carry researchDossier.metadata
+      // so the anti-repeat ledger and freshness gate become available without
+      // touching existing tokens, anchor, or palette.
+      const migrationResult = await migrateExistingDesignIntentToResearchDossierSchema(designIntentTargetPath);
+      if (migrationResult.migrated) {
+        supplementalMaterializedDocFileNames.push('design-intent.json (research-dossier metadata migrated)');
+        console.log('\n[MIGRATED] docs/design-intent.json now carries researchDossier.metadata. Run research-design.md before next UI implementation to populate the dossier and refresh researchVerifiedAt.');
+      }
     }
 
     await writeSelectedPolicy(resolvedTargetDirectoryPath, selectedPolicyProfileName);

package/lib/cli/commands/upgrade.mjs

@@ -45,6 +45,7 @@ import {
   detectProjectDocTemplateStaleness,
   buildDesignIntentSeedFromSignals,
 } from '../project-scaffolder.mjs';
+import { migrateExistingDesignIntentToResearchDossierSchema } from '../project-scaffolder/design-contract/research-dossier-migration.mjs';
 import { ensureActiveMemorySnapshot } from '../memory-continuity.mjs';
 import { buildExistingProjectMajorConstraints } from '../init-detection-flow.mjs';
 
@@ -388,6 +389,16 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         await ensureDirectory(docsDirectoryPath);
         await fs.writeFile(designIntentTargetPath, designIntentSeedContent, 'utf8');
         supplementalCreatedFileNames.push('docs/design-intent.json');
+      } else {
+        // Scenario D: existing project already has docs/design-intent.json.
+        // Inject researchDossier.metadata when absent so the anti-repeat ledger
+        // becomes available and active validation can enforce freshness.
+        const existingDesignIntentPath = path.join(resolvedTargetDirectoryPath, 'docs', 'design-intent.json');
+        const migrationResult = await migrateExistingDesignIntentToResearchDossierSchema(existingDesignIntentPath);
+        if (migrationResult.migrated) {
+          supplementalCreatedFileNames.push('docs/design-intent.json (research-dossier metadata migrated)');
+          console.log('\n[MIGRATED] docs/design-intent.json now carries researchDossier.metadata. Run research-design.md before next UI implementation to populate the dossier and refresh researchVerifiedAt.');
+        }
       }
 
       if (shouldEnsureActiveMemorySnapshot) {

package/lib/cli/project-scaffolder/design-contract/research-dossier-migration.mjs

@@ -0,0 +1,165 @@
+/**
+ * Research-dossier migration helper.
+ *
+ * Adds the `researchDossier.metadata` block to existing `docs/design-intent.json`
+ * files when it is absent, populating `antiRepeatLedger` from the existing
+ * conceptual anchor, palette, and motion fields so future UI work cannot
+ * unknowingly repeat shipped direction.
+ *
+ * Idempotent: if the metadata block already exists, the file is left untouched.
+ * Additive: never overwrites existing fields.
+ */
+
+import fs from 'node:fs/promises';
+
+import { pathExists } from '../../utils.mjs';
+
+const FRESHNESS_WINDOW_DAYS = 90;
+const FRESHNESS_RULE = 'Research dossier is stale when researchVerifiedAt is null or older than freshnessWindowDays. Stale dossiers must run research-design.md before UI implementation. User-explicit redesign requests bypass freshness and force fresh research regardless of age.';
+
+function takeFirstNonEmpty(...candidateValues) {
+  for (const candidateValue of candidateValues) {
+    if (typeof candidateValue === 'string' && candidateValue.trim().length > 0) {
+      return candidateValue.trim();
+    }
+  }
+  return null;
+}
+
+function buildPreviousAnchorEntry(designIntentContract) {
+  const conceptualAnchor = designIntentContract?.conceptualAnchor;
+  if (!conceptualAnchor || typeof conceptualAnchor !== 'object') {
+    return [];
+  }
+  const anchorReference = takeFirstNonEmpty(conceptualAnchor.anchorReference);
+  if (!anchorReference || anchorReference === 'agent-defined-anchor-reference') {
+    return [];
+  }
+  const specificReferencePoint = takeFirstNonEmpty(conceptualAnchor.specificReferencePoint);
+  const summary = specificReferencePoint
+    ? `${anchorReference} (${specificReferencePoint})`
+    : anchorReference;
+  return [{
+    summary,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-direction',
+  }];
+}
+
+function buildPreviousPaletteEntry(designIntentContract) {
+  const derivedTokenLogic = designIntentContract?.derivedTokenLogic;
+  const colorTruth = designIntentContract?.colorTruth;
+  const colorDerivationSummary = takeFirstNonEmpty(derivedTokenLogic?.colorDerivationSource);
+  const colorIntent = takeFirstNonEmpty(colorTruth?.intent);
+  const summary = takeFirstNonEmpty(colorIntent, colorDerivationSummary);
+  if (!summary) {
+    return [];
+  }
+  return [{
+    summary,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-palette-behavior',
+  }];
+}
+
+function buildPreviousMotionEntry(designIntentContract) {
+  const motionPaletteDecision = designIntentContract?.motionPaletteDecision;
+  const motionSystem = designIntentContract?.motionSystem;
+  const derivedTokenLogic = designIntentContract?.derivedTokenLogic;
+
+  const motionSignature = takeFirstNonEmpty(
+    motionPaletteDecision?.signatureMotion,
+    motionPaletteDecision?.motion,
+    motionSystem?.signature,
+    motionSystem?.purpose,
+    derivedTokenLogic?.motionBudget,
+  );
+  if (!motionSignature) {
+    return [];
+  }
+  return [{
+    summary: motionSignature,
+    source: 'migrated-from-existing-design-intent',
+    blockedBecause: 'previously-shipped-motion-signature',
+  }];
+}
+
+export function buildResearchDossierMetadata({
+  designIntentContract = null,
+  populateLedgerFromExistingContract = false,
+} = {}) {
+  const metadata = {
+    researchVerifiedAt: null,
+    freshnessWindowDays: FRESHNESS_WINDOW_DAYS,
+    freshnessRule: FRESHNESS_RULE,
+    antiRepeatLedger: {
+      blocklistFromHistory: true,
+      ledgerScope: 'signature-level-descriptors-only',
+      ledgerMaxEntriesPerCategory: 3,
+      previousAnchors: [],
+      previousPalettes: [],
+      previousMotionSignatures: [],
+    },
+    userExplicitRedesignBypassesFreshness: true,
+    statusAwareValidation: {
+      seedStatuses: [
+        'seed-needs-design-synthesis',
+        'seed-generated-during-init',
+        'seed-generated-during-upgrade',
+      ],
+      seedSkipsDossierShape: true,
+      activeRequiresFreshOrExplicitRedesign: true,
+    },
+  };
+
+  if (populateLedgerFromExistingContract && designIntentContract && typeof designIntentContract === 'object') {
+    metadata.antiRepeatLedger.previousAnchors = buildPreviousAnchorEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
+    metadata.antiRepeatLedger.previousPalettes = buildPreviousPaletteEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
+    metadata.antiRepeatLedger.previousMotionSignatures = buildPreviousMotionEntry(designIntentContract).slice(0, metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory);
+  }
+
+  return metadata;
+}
+
+/**
+ * Migrates an existing design-intent.json file in place by adding
+ * `researchDossier.metadata` when absent. Idempotent.
+ *
+ * @param {string} designIntentFilePath
+ * @returns {Promise<{ migrated: boolean, reason: string }>}
+ */
+export async function migrateExistingDesignIntentToResearchDossierSchema(designIntentFilePath) {
+  if (!(await pathExists(designIntentFilePath))) {
+    return { migrated: false, reason: 'design-intent-file-absent' };
+  }
+
+  const fileContent = await fs.readFile(designIntentFilePath, 'utf8');
+  let designIntentContract;
+  try {
+    designIntentContract = JSON.parse(fileContent);
+  } catch {
+    return { migrated: false, reason: 'design-intent-file-not-valid-json' };
+  }
+
+  if (!designIntentContract || typeof designIntentContract !== 'object') {
+    return { migrated: false, reason: 'design-intent-file-not-an-object' };
+  }
+
+  const existingResearchDossier = designIntentContract.researchDossier;
+  if (existingResearchDossier && typeof existingResearchDossier === 'object' && existingResearchDossier.metadata) {
+    return { migrated: false, reason: 'research-dossier-metadata-already-present' };
+  }
+
+  const populatedMetadata = buildResearchDossierMetadata({
+    designIntentContract,
+    populateLedgerFromExistingContract: true,
+  });
+
+  designIntentContract.researchDossier = {
+    ...(existingResearchDossier && typeof existingResearchDossier === 'object' ? existingResearchDossier : {}),
+    metadata: populatedMetadata,
+  };
+
+  await fs.writeFile(designIntentFilePath, `${JSON.stringify(designIntentContract, null, 2)}\n`, 'utf8');
+  return { migrated: true, reason: 'research-dossier-metadata-injected' };
+}

package/lib/cli/project-scaffolder/design-contract/sections/conceptual-anchor.mjs

@@ -2,6 +2,12 @@
  * Conceptual anchor section of the design intent contract. Encodes the rules
  * 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
+ * `.agent-context/prompts/research-design.md`:
+ *   - categoryCodes (Section 3)
+ *   - morphologicalExploration (Section 4)
+ *   - anchorCandidates (Section 5)
  */
 
 export function buildConceptualAnchorSection() {
@@ -9,6 +15,7 @@ export function buildConceptualAnchorSection() {
     mode: 'required-when-no-external-research',
     seedMode: 'selection-policy-only',
     anchorReference: 'agent-defined-anchor-reference',
+    researchBrief: '.agent-context/prompts/research-design.md',
     requiresAgentSelectionBeforeUiImplementation: true,
     userResearchAbsencePolicy: {
       userSuppliedResearchOnly: true,
@@ -88,6 +95,116 @@ export function buildConceptualAnchorSection() {
       'motion',
       'responsive-composition',
     ],
+    categoryCodes: {
+      mode: 'agent-must-complete-before-ui-implementation',
+      blockingByDefault: true,
+      researchBriefSection: 'Section 3',
+      researchBriefPath: '.agent-context/prompts/research-design.md',
+      minimumEntries: 3,
+      specificityRule: 'A category code is only valid if a reader unfamiliar with the project can visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name.',
+      antiLeakageRule: 'Listing a cliche identifies a trap; it does not endorse an aesthetic. Examples in the brief are NOT target aesthetics for any project. Each category code must carry an explicit rejection note so the cliche cannot quietly become the target.',
+      failingExamples: [
+        'clean typography (too abstract, applies to anything)',
+        'modern color palette (not falsifiable)',
+        'smooth animations (describes nothing specific)',
+      ],
+      passingExamples: [
+        "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)',
+      ],
+      passingExamplesPolicy: 'These examples illustrate the description format only. They are AI-defaultable cliches of their categories and must NOT be adopted as target aesthetics for any project.',
+      commonAiSafeClichesToReject: [
+        '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',
+        'marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid',
+      ],
+      commonAiSafeClichesPolicy: 'If the project sits anywhere near one of these AI-safe defaults, the matching cliche must appear in candidateEntries with an explicit rejection note. Software products pattern-match one of these without intervention; naming the trap is required even when the trap is uncomfortable to admit.',
+      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',
+      ],
+      forbiddenPlaceholderPhrases: [
+        'clean typography',
+        'modern color palette',
+        'smooth animations',
+        'best practices',
+        'good design',
+      ],
+      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

@@ -7,6 +7,12 @@
 
 import { hasNonEmptyString } from './helpers.mjs';
 
+const SEED_STATUSES = new Set([
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+]);
+
 function validateUserResearchAbsencePolicy(conceptualAnchor, validationErrors) {
   const userResearchAbsencePolicy = conceptualAnchor.userResearchAbsencePolicy;
   if (!userResearchAbsencePolicy || typeof userResearchAbsencePolicy !== 'object') {
@@ -166,6 +172,8 @@ export function validateConceptualAnchor(designIntentContract, validationErrors)
   }
 
   const conceptualAnchor = designIntentContract.conceptualAnchor;
+  const isSeedStatus = SEED_STATUSES.has(designIntentContract.status);
+
   if (conceptualAnchor.mode !== 'required-when-no-external-research') {
     validationErrors.push('designIntent.conceptualAnchor.mode must equal "required-when-no-external-research".');
   }
@@ -204,6 +212,9 @@ 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;
 }
 
@@ -220,3 +231,226 @@ export function validateMathSystems(designIntentContract, validationErrors) {
   }
   return validationErrors;
 }
+
+function validateCategoryCodes(conceptualAnchor, validationErrors, options = {}) {
+  const { isSeedStatus = false } = options;
+  const categoryCodes = conceptualAnchor.categoryCodes;
+  if (!categoryCodes || typeof categoryCodes !== 'object') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes must exist (Section 3 of research-design.md).');
+    return;
+  }
+  if (categoryCodes.mode !== 'agent-must-complete-before-ui-implementation') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.mode must equal "agent-must-complete-before-ui-implementation".');
+  }
+  if (categoryCodes.blockingByDefault !== true) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.blockingByDefault must equal true.');
+  }
+  if (categoryCodes.researchBriefSection !== 'Section 3') {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.researchBriefSection must equal "Section 3".');
+  }
+  if (!hasNonEmptyString(categoryCodes.researchBriefPath) || !categoryCodes.researchBriefPath.includes('research-design.md')) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.researchBriefPath must point to the research-design.md brief.');
+  }
+  if (!Number.isInteger(categoryCodes.minimumEntries) || categoryCodes.minimumEntries < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.minimumEntries must be an integer >= 3.');
+  }
+  if (!hasNonEmptyString(categoryCodes.specificityRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.specificityRule must be a non-empty string.');
+  }
+  if (!hasNonEmptyString(categoryCodes.antiLeakageRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.antiLeakageRule must be a non-empty string that prevents the example cliches from being read as target aesthetics.');
+  }
+  if (!hasNonEmptyString(categoryCodes.selfTestRule)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.selfTestRule must be a non-empty string.');
+  }
+  if (!Array.isArray(categoryCodes.failingExamples) || categoryCodes.failingExamples.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.failingExamples must list at least 3 failing examples to anchor the specificity floor.');
+  }
+  if (!Array.isArray(categoryCodes.passingExamples) || categoryCodes.passingExamples.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.passingExamples must list at least 3 passing examples to anchor the specificity floor.');
+  }
+  if (!hasNonEmptyString(categoryCodes.passingExamplesPolicy)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.passingExamplesPolicy must be a non-empty string clarifying that the passing examples are description-format illustrations, not target aesthetics.');
+  }
+  if (!Array.isArray(categoryCodes.commonAiSafeClichesToReject) || categoryCodes.commonAiSafeClichesToReject.length < 3) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.commonAiSafeClichesToReject must list at least 3 AI-safe defaults the agent has to name and reject when the project sits near them.');
+  }
+  if (!hasNonEmptyString(categoryCodes.commonAiSafeClichesPolicy)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.commonAiSafeClichesPolicy must be a non-empty string requiring the matching cliche to appear with a rejection note when the project pattern-matches it.');
+  }
+  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.');
+  }
+  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.');
+  }
+  if (!Array.isArray(categoryCodes.candidateEntries)) {
+    validationErrors.push('designIntent.conceptualAnchor.categoryCodes.candidateEntries must be an array (empty in the seed; populated by the agent).');
+  }
+}
+
+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/validation/research-dossier-validators.mjs

@@ -0,0 +1,104 @@
+/**
+ * Research dossier validators. Enforces the `researchDossier.metadata` block
+ * shape that powers the freshness gate, status-aware skip, and anti-repeat
+ * ledger consumed by `.agent-context/prompts/research-design.md`.
+ */
+
+import { hasNonEmptyString } from './helpers.mjs';
+
+const REQUIRED_FRESHNESS_WINDOW_DAYS = 90;
+const REQUIRED_SEED_STATUSES = [
+  'seed-needs-design-synthesis',
+  'seed-generated-during-init',
+  'seed-generated-during-upgrade',
+];
+const ANTI_REPEAT_LEDGER_CATEGORIES = ['previousAnchors', 'previousPalettes', 'previousMotionSignatures'];
+
+function validateMetadataBaseShape(metadata, validationErrors) {
+  if (
+    metadata.researchVerifiedAt !== null
+    && (typeof metadata.researchVerifiedAt !== 'string' || metadata.researchVerifiedAt.trim().length === 0)
+  ) {
+    validationErrors.push('designIntent.researchDossier.metadata.researchVerifiedAt must be null or an ISO date string.');
+  }
+  if (!Number.isInteger(metadata.freshnessWindowDays) || metadata.freshnessWindowDays < 1) {
+    validationErrors.push(`designIntent.researchDossier.metadata.freshnessWindowDays must be a positive integer (recommended ${REQUIRED_FRESHNESS_WINDOW_DAYS}).`);
+  }
+  if (!hasNonEmptyString(metadata.freshnessRule)) {
+    validationErrors.push('designIntent.researchDossier.metadata.freshnessRule must be a non-empty string explaining staleness.');
+  }
+  if (metadata.userExplicitRedesignBypassesFreshness !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.userExplicitRedesignBypassesFreshness must equal true so explicit redesign requests force fresh research.');
+  }
+}
+
+function validateStatusAwareValidation(metadata, validationErrors) {
+  const statusAwareValidation = metadata.statusAwareValidation;
+  if (!statusAwareValidation || typeof statusAwareValidation !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation must exist.');
+    return;
+  }
+  const seedStatuses = statusAwareValidation.seedStatuses;
+  const hasAllRequiredSeedStatuses = Array.isArray(seedStatuses)
+    && REQUIRED_SEED_STATUSES.every((requiredSeedStatusName) => seedStatuses.includes(requiredSeedStatusName));
+  if (!hasAllRequiredSeedStatuses) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.seedStatuses must include seed-needs-design-synthesis, seed-generated-during-init, and seed-generated-during-upgrade.');
+  }
+  if (statusAwareValidation.seedSkipsDossierShape !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.seedSkipsDossierShape must equal true.');
+  }
+  if (statusAwareValidation.activeRequiresFreshOrExplicitRedesign !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.statusAwareValidation.activeRequiresFreshOrExplicitRedesign must equal true.');
+  }
+}
+
+function validateAntiRepeatLedger(metadata, validationErrors) {
+  const antiRepeatLedger = metadata.antiRepeatLedger;
+  if (!antiRepeatLedger || typeof antiRepeatLedger !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger must exist.');
+    return;
+  }
+  if (antiRepeatLedger.blocklistFromHistory !== true) {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.blocklistFromHistory must equal true so previously shipped direction is blocked from repetition.');
+  }
+  if (antiRepeatLedger.ledgerScope !== 'signature-level-descriptors-only') {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.ledgerScope must equal "signature-level-descriptors-only" so the ledger does not become a raw token dump.');
+  }
+  if (
+    !Number.isInteger(antiRepeatLedger.ledgerMaxEntriesPerCategory)
+    || antiRepeatLedger.ledgerMaxEntriesPerCategory < 1
+    || antiRepeatLedger.ledgerMaxEntriesPerCategory > 5
+  ) {
+    validationErrors.push('designIntent.researchDossier.metadata.antiRepeatLedger.ledgerMaxEntriesPerCategory must be an integer between 1 and 5 to keep the ledger signature-level.');
+  }
+  for (const ledgerCategoryName of ANTI_REPEAT_LEDGER_CATEGORIES) {
+    const ledgerEntries = antiRepeatLedger[ledgerCategoryName];
+    if (!Array.isArray(ledgerEntries)) {
+      validationErrors.push(`designIntent.researchDossier.metadata.antiRepeatLedger.${ledgerCategoryName} must be an array (may be empty in fresh seeds).`);
+      continue;
+    }
+    if (
+      Number.isInteger(antiRepeatLedger.ledgerMaxEntriesPerCategory)
+      && ledgerEntries.length > antiRepeatLedger.ledgerMaxEntriesPerCategory
+    ) {
+      validationErrors.push(`designIntent.researchDossier.metadata.antiRepeatLedger.${ledgerCategoryName} exceeds ledgerMaxEntriesPerCategory; trim to signature-level descriptors.`);
+    }
+  }
+}
+
+export function validateResearchDossier(designIntentContract, validationErrors) {
+  const researchDossier = designIntentContract?.researchDossier;
+  if (!researchDossier || typeof researchDossier !== 'object') {
+    validationErrors.push('designIntent.researchDossier must exist (Section 3-5 metadata block from research-design.md).');
+    return validationErrors;
+  }
+  const metadata = researchDossier.metadata;
+  if (!metadata || typeof metadata !== 'object') {
+    validationErrors.push('designIntent.researchDossier.metadata must exist with researchVerifiedAt, freshnessWindowDays, and antiRepeatLedger.');
+    return validationErrors;
+  }
+  validateMetadataBaseShape(metadata, validationErrors);
+  validateStatusAwareValidation(metadata, validationErrors);
+  validateAntiRepeatLedger(metadata, validationErrors);
+  return validationErrors;
+}

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

@@ -18,6 +18,7 @@ import {
   validateConceptualAnchor,
   validateMathSystems,
 } from './validation/anchor-validators.mjs';
+import { validateResearchDossier } from './validation/research-dossier-validators.mjs';
 import {
   validateAiSafeUiAudit,
   validateProductionContentPolicy,
@@ -54,6 +55,7 @@ export function validateDesignIntentContract(designIntentContract) {
   validateDesignFlexibilityPolicy(designIntentContract, validationErrors);
   validateConceptualAnchor(designIntentContract, validationErrors);
   validateMathSystems(designIntentContract, validationErrors);
+  validateResearchDossier(designIntentContract, validationErrors);
   validateAiSafeUiAudit(designIntentContract, validationErrors);
   validateProductionContentPolicy(designIntentContract, validationErrors);
   validateTokenSystem(designIntentContract, validationErrors);

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

@@ -22,6 +22,7 @@ import {
 import { buildStructureFirstSeedSignals, shouldBootstrapDesignDocument } from './design-contract/seed-signals.mjs';
 import { FORBIDDEN_PATTERN_SIGNALS } from './design-contract/signal-vocab.mjs';
 import { buildConceptualAnchorSection } from './design-contract/sections/conceptual-anchor.mjs';
+import { buildResearchDossierMetadata } from './design-contract/research-dossier-migration.mjs';
 import {
   buildAccessibilityPolicySection,
   buildAiSafeUiAuditSection,
@@ -124,6 +125,9 @@ function buildDesignIntentContractObject({
       externalInspirationPolicy: 'External websites and examples are candidate evidence for constraints, mechanics, and quality bars; do not copy their layout rhythm, palette, component skin, brand posture, or visual metaphor.',
     },
     conceptualAnchor: buildConceptualAnchorSection(),
+    researchDossier: {
+      metadata: buildResearchDossierMetadata(),
+    },
     derivedTokenLogic: {
       anchorReference: 'agent-defined-anchor-reference',
       colorDerivationSource: 'Explain semantic color roles from anchorReference; reject generic palettes without anchor evidence.',
@@ -274,6 +278,7 @@ function buildDesignIntentContractObject({
       bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
       autoLoadedRuleFiles: [
         '.agent-context/prompts/bootstrap-design.md',
+        '.agent-context/prompts/research-design.md',
         '.agent-context/rules/frontend-architecture.md',
       ],
       disallowedAutoLoadedRuleFiles: [

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

@@ -190,6 +190,7 @@ export function buildDesignBootstrapPrompt({
     '29. repoEvidence when onboarding or detector evidence exists',
     '',
     '## Mechanical Gates',
+    '0. Read `.agent-context/prompts/research-design.md` first. Sections 3 (Category Code Identification), 4 (Morphological Exploration), and 5 (Anchor Candidates) are gates: each must produce an auditable artifact before UI implementation.',
     '1. Do not copy external style guides.',
     '2. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
     '3. Do not choose final style, library, palette, typography, motion, or layout from this offline scaffold.',
@@ -238,6 +239,13 @@ export function buildDesignBootstrapPrompt({
     '40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
     '41. Use external websites and benchmark examples as candidate evidence for constraints, mechanics, and quality bars only; do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture.',
     '',
+    '## Research-Design Brief Gates (research-design.md)',
+    '42. Section 3 — Category Code Identification: list at least three category codes per product surface in `conceptualAnchor.categoryCodes.candidateEntries`. Each entry must record `description`, `specificityEvidence`, `categoryDefaultReason`, and `rejectionNote`. The specificity floor is: a reader unfamiliar with the project must be able to visualize a specific aesthetic direction from the text alone, without seeing the UI and without knowing the product name. Reject placeholder phrases like "clean typography", "modern color palette", or "smooth animations". Anti-leakage rule: listing a cliche identifies a trap, not a target; the example cliches in the brief are not aesthetic candidates for any project. If the project pattern-matches a common AI-safe default (dev-tool dark slate, AI-startup purple-pink gradient, health-app mint, SaaS admin three-card KPI, marketing-site three-tile hero), name that cliche in `candidateEntries` with an explicit rejection note.',
+    '43. Section 4 — Morphological Exploration: build a 5x5 or 6x5 matrix in `conceptualAnchor.morphologicalExploration`. Choose 5 or 6 dimensions and 5 values per dimension. Do not seed the matrix with the Section 3 category codes as values. Highlight the selected combination, and ALSO highlight at least one uncomfortable combination that feels instinctively wrong but can be argued with product logic. The uncomfortable combination must record `combinationLabel`, `discomfortReason`, and `productLogicJustification`. If you cannot produce an uncomfortable-but-arguable combination, the dimensions are too narrow; widen at least one and regenerate.',
+    '44. Section 5 — Anchor Candidates: produce exactly five entries in `conceptualAnchor.anchorCandidates.candidates`. Each candidate must record `anchorReference`, `conceptualFamily`, `jobFit`, `hierarchyImplication`, `densityImplication`, `typeImplication`, `stateLanguage`, `motionImplication`, `whatItRulesOut`, `renameTest`, and `categoryCodeOverlap`.',
+    '45. Strengthened rename test: rename the product to three genuinely different categories that are remote from each other and from the actual product. Pick fresh test categories per anchor; do not reuse the same triple across every anchor. Record the three test categories explicitly in the dossier so a human reviewer can audit them. Score the result: 0/3 coherent equals STRONG PASS, 1/3 equals PASS, 2/3 equals REVISE, 3/3 equals DISCARD. Never select an anchor with verdict DISCARD; revise REVISE candidates until they fail in at least 2 of 3 categories.',
+    '46. Make `conceptualAnchor.anchorReference` and `derivedTokenLogic.anchorReference` match the selected anchor exactly. The selected anchor must have verdict STRONG PASS or PASS.',
+    '',
     '## Creative Ambition Floor',
     'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
     'The ambition floor is not a fixed aesthetic. Quiet, dense, utilitarian, or text-heavy interfaces are allowed when the product requires them, but they still need a project-specific visual decision and a real reason for omitting richer motion, 3D, canvas, WebGL, scroll choreography, or animation libraries.',
@@ -290,6 +298,7 @@ export function buildDesignBootstrapPrompt({
     '13. Preserve externalResearchIntake so user-provided research becomes reviewed evidence without turning into an offline style or dependency preset.',
     '14. Preserve conceptualAnchor so prompt-only UI work has one cohesive non-template concept instead of a mixed collection of bold but unrelated visual decisions.',
     '15. Record conceptualAnchor.agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, visualRiskBudget, motionRiskBudget, and cohesionChecks so the final UI cannot quietly fall back to a timid dashboard/admin mental model.',
+    '15a. Record conceptualAnchor.categoryCodes.candidateEntries (Section 3 of research-design.md), conceptualAnchor.morphologicalExploration with selectedCombination and uncomfortableCombination (Section 4), and conceptualAnchor.anchorCandidates.candidates with full renameTest results (Section 5) before UI implementation.',
     '16. Preserve derivedTokenLogic, libraryResearchStatus, and libraryDecisions so token choices and dependency uncertainty stay visible before implementation.',
     '16a. Preserve designFlexibilityPolicy so the machine contract guides consistency without freezing literal anchor artifacts, exact token primitives, or component-kit visual language.',
     '17. Preserve productionContentPolicy so UI output is ship-ready and not a testing-looking scaffold.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -83,7 +83,7 @@
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "clean:local": "node ./scripts/clean-local-artifacts.mjs",
     "validate": "node ./scripts/validate.mjs",
-    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
+    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./tests/research-dossier-migration.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.96.0",

package/scripts/audit-caching-scope-hygiene.mjs

@@ -6,7 +6,7 @@
  *
  * Phase 5 drift catcher. Scans user-facing surfaces (README, AGENTS.md, FAQ,
  * integration playbook, CHANGELOG) for caching numerical claims and verifies
- * that each claim is integration-scoped per `docs/plan/research-foundation.md`
+ * that each claim is integration-scoped per `docs/architecture/decisions-foundation.md`
  * D4 "Per-Tool Caching Scope Matrix".
  *
  * The rule: never publish a single universal "X% caching saving" figure that
@@ -16,8 +16,8 @@
  *      (direct API, Claude Code SDK programmatic, Cursor, Windsurf, Codex CLI,
  *      Kiro, IDE wrapper) within +/- 600 characters of the figure, OR
  *   2. live in a documented exempt context (Phase 1 aggregate-cap CHANGELOG
- *      rationale, plan files under docs/plan/, benchmark JSON under
- *      benchmarks/results/, the canonical D4 matrix itself).
+ *      rationale, archived plan files under docs/archive/, benchmark JSON
+ *      under benchmarks/results/, the canonical D4 matrix itself).
  */
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -200,7 +200,7 @@ export function runCachingScopeHygieneAudit(options = {}) {
           file: surfacePath,
           line: lineNumber,
           kind: 'caching-claim.missing-integration-scope',
-          detail: `Caching saving claim "${claim.matchedText.trim()}" lacks an integration-mode marker within +/- ${CONTEXT_WINDOW_RADIUS} chars. Add a per-tool / direct-API / IDE-wrapper label, or move the figure under a clearly-scoped paragraph. Source of truth: docs/plan/research-foundation.md D4.`,
+          detail: `Caching saving claim "${claim.matchedText.trim()}" lacks an integration-mode marker within +/- ${CONTEXT_WINDOW_RADIUS} chars. Add a per-tool / direct-API / IDE-wrapper label, or move the figure under a clearly-scoped paragraph. Source of truth: docs/architecture/decisions-foundation.md D4.`,
         });
       }
     }

package/scripts/build-release-benchmark-bundle.mjs

@@ -31,7 +31,7 @@ const SOURCE_ARTIFACTS = [
     artifactId: 'phase-2-cache',
     relativePath: 'benchmarks/results/cache-phase-2-2026-05-16.json',
     role: 'cache-simulation',
-    description: 'Phase 2 offline warm-cache simulation. Direct provider API integration mode; see docs/plan/research-foundation.md D4 for the per-tool scope matrix.',
+    description: 'Phase 2 offline warm-cache simulation. Direct provider API integration mode; see docs/architecture/decisions-foundation.md D4 for the per-tool scope matrix.',
   },
   {
     artifactId: 'phase-3-anti-halu',
@@ -145,12 +145,12 @@ export function buildReleaseBenchmarkBundle(options = {}) {
     generated_at: new Date().toISOString(),
     description: 'Phase 5 release benchmark bundle. References Phase 0-3 locked artifacts plus the Phase 5 supply-chain snapshot. No artifact is regenerated by this bundle. Artifact integrity is verified by SHA-256 hash via scripts/audit-release-bundle.mjs.',
     sources: {
-      research_foundation: 'docs/plan/research-foundation.md',
-      d4_caching_scope_matrix: 'docs/plan/research-foundation.md#d4',
+      research_foundation: 'docs/architecture/decisions-foundation.md',
+      d4_caching_scope_matrix: 'docs/architecture/decisions-foundation.md#d4',
       caching_reporting_format: 'docs/benchmark-reference.md',
-      phase_2_outcome: 'docs/plan/phase-2-outcome.md',
-      phase_3_outcome: 'docs/plan/phase-3-outcome.md',
-      phase_5_plan: 'docs/plan/phase-5-hardening.md',
+      phase_2_outcome: 'docs/archive/phase-2-outcome.md',
+      phase_3_outcome: 'docs/archive/phase-3-outcome.md',
+      phase_5_plan: 'docs/archive/phase-5-hardening.md',
     },
     integrity: {
       hash_algorithm: 'SHA-256',

package/scripts/migrate-rule-format/id-prefix-table.mjs

@@ -1,7 +1,7 @@
 // @ts-check
 
 /**
- * Locked ID prefix table per `docs/plan/format-spec.md` section 3.
+ * Locked ID prefix table per `docs/architecture/format-spec.md` section 3.
  * The migration helper reads this map to assign frontmatter and section IDs.
  * Lock new entries here when adding a new rule file; never invent prefixes inline.
  */

package/scripts/migrate-rule-format/render-new.mjs

@@ -2,7 +2,7 @@
 
 /**
  * Renders a parsed legacy rule file plus a prefix-table entry into the v4
- * canonical format defined in `docs/plan/format-spec.md`.
+ * canonical format defined in `docs/architecture/format-spec.md`.
  *
  * Section IDs auto-assign sequentially starting at 001. The renderer never
  * skips integers; humans introduce gaps manually during review by editing

package/scripts/migrate-rule-format.mjs

@@ -5,7 +5,7 @@
  * scripts/migrate-rule-format.mjs
  *
  * Phase 1 Task 1.2 migration helper. Converts a legacy v3 rule file into the
- * canonical v4 format defined in docs/plan/format-spec.md. Output is written
+ * canonical v4 format defined in docs/architecture/format-spec.md. Output is written
  * to a `.candidate.md` sibling so the human migrator can review the diff
  * before replacing the original.
  *

package/scripts/validate/config.mjs

@@ -301,6 +301,12 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'Motion/Palette Decision',
       'product categories are heuristics',
       'perform live web research',
+      'research-design.md',
+      'researchDossier.metadata',
+      'researchVerifiedAt',
+      'freshnessWindowDays',
+      'Anti-repeat ledger',
+      'user-explicit redesign',
     ],
   },
   {
@@ -352,6 +358,24 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'A new dependency, package count, or vague performance concern is not a blocker by itself.',
       '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`',
+    ],
+  },
+  {
+    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',
+      'Anti-Repeat Ledger Gate',
+      'previousAnchors',
+      'previousMotionSignatures',
     ],
   },
   {

package/scripts/validate.mjs

@@ -158,6 +158,7 @@ async function validateRequiredFiles() {
     'scripts/release-gate.mjs',
     'scripts/generate-sbom.mjs',
     '.agent-context/policies/llm-judge-threshold.json',
+    '.agent-context/prompts/research-design.md',
     'mcp.json',
     'AGENTS.md',
     'CLAUDE.md',