@vpxa/aikit 0.1.350 → 0.1.351

package/scaffold/dist/definitions/agents.mjs

@@ -24,6 +24,6 @@ ${l}
 ${e(a)}
 
 ${o}
-${s}`}}const i={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[`layered-knowledge-operating-policy`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit recall, flow status, search, and ctx ref reuse`],[`multi-agents-development`,`Before delegation — decomposition, dispatch envelope, review pipeline`],[`present`,`For plans, reviews, evidence maps, approvals, and non-tiny user output`],[`brainstorming`,`For design forks, trade-offs, or creative requirements`],[`requirements-clarity`,`For vague, large, or cross-team requirements before planning`],[`c4-architecture`,`For architecture diagrams, boundary questions, or structure docs`],[`adr-skill`,`For non-trivial technical decisions and ADR lifecycle`],[`docs`,`For docs-sync, durable docs, PRDs, tours, and architecture docs`],[`lesson-learned`,`After implementation/review work — persist reusable engineering lessons`],[`session-handoff`,`When context pressure rises or work must pause/resume`],[`repo-access`,`For private/self-hosted repo access failures`],[`browser-use`,`For browser auth, JS-rendered pages, visual verification, web automation`]],subagentConstraints:["Do NOT use the `present` tool — return all findings as structured text.","Do NOT call `get_changed_files` — it returns ALL uncommitted diffs (100K+ tokens). Use `git diff <file>` if needed.",`No flow advancement. Only Orchestrator advances the flow.`,"Return status: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`. ≤200 words for normal status; full detail only if BLOCKED.",`Stay inside assigned files and boundary. Do not modify files outside scope.`]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,compactRole:`TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`planning-principles`,`layered-knowledge-operating-policy`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit reading plans, recall, and compressed context reuse`],[`multi-agents-development`,`For decomposition, dependency batches, and dispatch envelopes`],[`brainstorming`,`For new feature/behavior planning and design alternatives`],[`requirements-clarity`,`For vague or large requirements before planning`],[`present`,`For plan, dependency graph, risk matrix, and approval display`],[`c4-architecture`,`For architecture changes and C4 diagrams`],[`adr-skill`,`For non-trivial technical decisions and ADRs`],[`session-handoff`,`For context pressure or session end`],[`repo-access`,`For private or self-hosted repo access`],[`browser-use`,`For auth recovery or browser workflows`]]},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,compactRole:`New features, wire up, build`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`react`,`When implementing React components, hooks, or pages`],[`lesson-learned`,`After completing non-obvious implementation work`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,compactRole:`UI/UX, React, styling, responsive`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`],[`browser-use`,`When visual/browser verification is needed`],[`lesson-learned`,`After completing non-obvious frontend implementation work`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,compactRole:`Cleanup, simplify, DRY, extract`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When refactoring TypeScript code — type patterns, generics, utility types`],[`lesson-learned`,`After completing refactor — extract principles from before/after diff`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,compactRole:`Bug diagnosis, error tracing`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`browser-use`,`For browser/UI reproduction loops and JS-rendered failures`],[`repo-access`,`When debugging depends on private or enterprise repo access`],[`lesson-learned`,`After a non-obvious root cause or fix`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,compactRole:`Vulnerability analysis, auth hardening`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`],[`repo-access`,`When security review requires private/enterprise repo access`],[`browser-use`,`When reviewing browser auth, sessions, cookies, or web security flows`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,compactRole:`Project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`documentation-principles`,`layered-knowledge-operating-policy`],category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`c4-architecture`,`When documenting architecture, containers, components, or deployment`],[`adr-skill`,`When docs involve technical decisions or ADR updates`],[`typescript`,`When documenting TypeScript APIs, public types, or generated docs`],[`session-handoff`,`When docs work spans sessions or context pressure rises`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,compactRole:`Rapid codebase navigation`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,sharedProtocols:[`thinking-principles`,`layered-knowledge-operating-policy`],category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,compactRole:`Multi-model deep research`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,sharedProtocols:[`thinking-principles`,`layered-knowledge-operating-policy`],category:`research`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`lesson-learned`,`When analyzing past changes to extract engineering principles`],[`c4-architecture`,`When researching system architecture — produce C4 diagrams`],[`adr-skill`,`When the research involves a technical decision — draft an ADR`],[`repo-access`,`When research needs private or enterprise repository access`],[`browser-use`,`When web research needs login, JS rendering, or browser automation`]],variants:{Alpha:n({description:`Primary deep research agent — also serves as default Researcher`,lensName:`Contrarian`,lensDescription:`deep research`,lensPrompt:`actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,identityIntro:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design.`,requiredOutputSection:`Depth Analysis`,requiredOutputItems:[`Deep-dive into ONE chosen subsystem (most structurally central to the question)`,`Full evidence chain: file:line citations for every structural claim`,"At least 2 `file_summary` extracts woven into the narrative"],focusAreas:[`For every proposed approach, actively seek the fatal flaw or hidden assumption`,`Ask: "Under what conditions does this approach fail catastrophically?"`,`Prefer uncomfortable truths over comfortable consensus`],variantSummary:`You are the DEFAULT researcher. When the Orchestrator needs breadth + depth, they
+${s}`}}const i={Orchestrator:{title:`The Master Conductor`,description:`Master conductor that orchestrates the full development lifecycle: Planning → Implementation → Review → Recovery → Commit`,argumentHint:null,toolRole:`orchestrator`,sharedBase:null,sharedProtocols:[`layered-knowledge-operating-policy`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit recall, flow status, search, and ctx ref reuse`],[`multi-agents-development`,`Before delegation — decomposition, dispatch envelope, review pipeline`],[`present`,`For plans, reviews, evidence maps, approvals, and non-tiny user output`],[`brainstorming`,`For design forks, trade-offs, or creative requirements`],[`requirements-clarity`,`For vague, large, or cross-team requirements before planning`],[`c4-architecture`,`For architecture diagrams, boundary questions, or structure docs`],[`adr-skill`,`For non-trivial technical decisions and ADR lifecycle`],[`docs`,`For docs-sync, durable docs, PRDs, tours, and architecture docs`],[`lesson-learned`,`After implementation/review work — persist reusable engineering lessons`],[`session-handoff`,`When context pressure rises or work must pause/resume`],[`repo-access`,`For private/self-hosted repo access failures`],[`browser-use`,`For browser auth, JS-rendered pages, visual verification, web automation`]],subagentConstraints:["Do NOT use the `present` tool — return all findings as structured text.","Do NOT call `get_changed_files` — it returns ALL uncommitted diffs (100K+ tokens). Use `git diff <file>` if needed.",`No flow advancement. Only Orchestrator advances the flow.`,"Return status: `DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED`. ≤200 words for normal status; full detail only if BLOCKED.",`Stay inside assigned files and boundary. Do not modify files outside scope.`,"Respect `readonly: true|false` flag in dispatch envelope. When readonly=true, do NOT modify files. When readonly=false, follow normal file-modification scope."]},Planner:{title:`The Strategic Architect`,description:`Autonomous planner that researches codebases and writes comprehensive TDD implementation plans`,compactRole:`TDD implementation plans`,argumentHint:null,toolRole:`planner`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`planning-principles`,`layered-knowledge-operating-policy`],category:`orchestration`,skills:[[`aikit`,`**Always** — AI Kit reading plans, recall, and compressed context reuse`],[`multi-agents-development`,`For decomposition, dependency batches, and dispatch envelopes`],[`brainstorming`,`For new feature/behavior planning and design alternatives`],[`requirements-clarity`,`For vague or large requirements before planning`],[`present`,`For plan, dependency graph, risk matrix, and approval display`],[`c4-architecture`,`For architecture changes and C4 diagrams`],[`adr-skill`,`For non-trivial technical decisions and ADRs`],[`session-handoff`,`For context pressure or session end`],[`repo-access`,`For private or self-hosted repo access`],[`browser-use`,`For auth recovery or browser workflows`]]},Implementer:{title:`The Code Builder`,description:`Persistent implementation agent that writes code following TDD practices until all tasks are complete`,compactRole:`New features, wire up, build`,argumentHint:`Implementation task, feature, or phase from plan`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`react`,`When implementing React components, hooks, or pages`],[`lesson-learned`,`After completing non-obvious implementation work`]]},Frontend:{title:`The UI Specialist`,description:`UI/UX specialist for React, styling, responsive design, and frontend implementation`,compactRole:`UI/UX, React, styling, responsive`,argumentHint:`UI component, styling task, or frontend feature`,toolRole:`codeAgent`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`react`,`When building React components — hooks, patterns, Server Components`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`frontend-design`,`When implementing UI/UX — design systems, accessibility, responsive patterns`],[`browser-use`,`When visual/browser verification is needed`],[`lesson-learned`,`After completing non-obvious frontend implementation work`]]},Refactor:{title:`The Code Sculptor`,description:`Code refactoring specialist that improves structure, readability, and maintainability`,compactRole:`Cleanup, simplify, DRY, extract`,argumentHint:`Code, component, or pattern to refactor`,toolRole:`refactor`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`implementation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When refactoring TypeScript code — type patterns, generics, utility types`],[`lesson-learned`,`After completing refactor — extract principles from before/after diff`]]},Debugger:{title:`The Problem Solver`,description:`Expert debugger that diagnoses issues, traces errors, and provides solutions using AI Kit traces and compressed context before raw file reads`,compactRole:`Bug diagnosis, error tracing`,argumentHint:`Error message, stack trace, or description of issue`,toolRole:`debugger`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When writing TypeScript code — type patterns, generics, utility types`],[`browser-use`,`For browser/UI reproduction loops and JS-rendered failures`],[`repo-access`,`When debugging depends on private or enterprise repo access`],[`lesson-learned`,`After a non-obvious root cause or fix`]]},Security:{title:`The Vulnerability Hunter`,description:`Security specialist that analyzes code for vulnerabilities and compliance`,compactRole:`Vulnerability analysis, auth hardening`,argumentHint:`Code, feature, or component to security review`,toolRole:`security`,sharedBase:`code-agent-base`,sharedProtocols:[`engineering-principles`,`layered-knowledge-operating-policy`],category:`diagnostics`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing code — security patterns, type safety`],[`repo-access`,`When security review requires private/enterprise repo access`],[`browser-use`,`When reviewing browser auth, sessions, cookies, or web security flows`]]},Documenter:{title:`The Knowledge Keeper`,description:`Documentation specialist that creates and maintains comprehensive project documentation`,compactRole:`Project documentation`,argumentHint:`Component, API, feature, or area to document`,toolRole:`documenter`,sharedBase:`code-agent-base`,sharedProtocols:[`thinking-principles`,`documentation-principles`,`layered-knowledge-operating-policy`],category:`documentation`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`docs`,`When creating or updating project documentation — docs/ convention, architecture blueprints, Diátaxis framework`],[`present`,`When presenting documentation previews or architecture visuals to the user`],[`c4-architecture`,`When documenting architecture, containers, components, or deployment`],[`adr-skill`,`When docs involve technical decisions or ADR updates`],[`typescript`,`When documenting TypeScript APIs, public types, or generated docs`],[`session-handoff`,`When docs work spans sessions or context pressure rises`]]},Explorer:{title:`The Rapid Scout`,description:`Rapid codebase exploration to find files, usages, dependencies, and structural context`,compactRole:`Rapid codebase navigation`,argumentHint:`Find files, usages, and context related to: {topic or goal}`,toolRole:`explorer`,sharedBase:null,sharedProtocols:[`thinking-principles`,`layered-knowledge-operating-policy`],category:`exploration`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`]]},Researcher:{title:`The Context Gatherer`,description:`Deep analysis, architecture review, and multi-model decision protocol participant`,compactRole:`Multi-model deep research`,argumentHint:`Research question, problem statement, or subsystem to investigate`,toolRole:`researcher`,sharedBase:`researcher-base`,sharedProtocols:[`thinking-principles`,`layered-knowledge-operating-policy`],category:`research`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`lesson-learned`,`When analyzing past changes to extract engineering principles`],[`c4-architecture`,`When researching system architecture — produce C4 diagrams`],[`adr-skill`,`When the research involves a technical decision — draft an ADR`],[`repo-access`,`When research needs private or enterprise repository access`],[`browser-use`,`When web research needs login, JS rendering, or browser automation`]],variants:{Alpha:n({description:`Primary deep research agent — also serves as default Researcher`,lensName:`Contrarian`,lensDescription:`deep research`,lensPrompt:`actively look for flaws, fatal assumptions, and hidden risks in every approach. The best ideas survive adversarial pressure.`,identityIntro:`, the primary deep research agent. During multi-model decision sessions, you provide deep reasoning and nuanced system design.`,requiredOutputSection:`Depth Analysis`,requiredOutputItems:[`Deep-dive into ONE chosen subsystem (most structurally central to the question)`,`Full evidence chain: file:line citations for every structural claim`,"At least 2 `file_summary` extracts woven into the narrative"],focusAreas:[`For every proposed approach, actively seek the fatal flaw or hidden assumption`,`Ask: "Under what conditions does this approach fail catastrophically?"`,`Prefer uncomfortable truths over comfortable consensus`],variantSummary:`You are the DEFAULT researcher. When the Orchestrator needs breadth + depth, they
 dispatch you alone. Your lens: thorough, evidence-first, exhaustive + contrarian.`}),Beta:n({description:`Research variant — pragmatic analysis with focus on trade-offs and edge cases`,lensName:`First Principles`,lensDescription:`pragmatic analysis`,lensPrompt:`strip away assumptions, decompose to ground truths, and rebuild reasoning from scratch.`,identityIntro:`, a variant of the Researcher agent optimized for **pragmatic analysis**. Focus on trade-offs, edge cases, and practical constraints. Challenge assumptions and highlight risks the primary researcher may overlook.`,requiredOutputSection:`Failure Modes & Counter-Evidence`,requiredOutputItems:[`At least 3 adversarial claims challenging your own primary finding`,`For each counter-claim: the condition under which it would be TRUE, and the
   evidence (file:line or search receipt) that currently falsifies it`,"Any unresolved counter-evidence flagged as `⚠ UNRESOLVED`"],focusAreas:[`Strip every assumption: "Is this truly required, or just inherited convention?"`,`Decompose to ground truths, then rebuild the reasoning from scratch`,`If the current approach exists only because "that's how it's always been done", flag it`],variantSummary:"Your lens: pragmatic skepticism + first principles. Mark competing claims as `A` (Assumed)\nby default; challenge before promoting to `V`."}),Gamma:n({description:`Research variant — broad pattern matching across domains and technologies`,lensName:`Expansionist`,lensDescription:`cross-domain pattern matching`,lensPrompt:`look for the bigger opportunity, find what's undervalued, and identify patterns others dismiss.`,identityIntro:`, a variant of the Researcher agent optimized for **cross-domain pattern matching**. Draw connections from other domains, frameworks, and industries. Bring breadth where Alpha brings depth.`,requiredOutputSection:`Cross-Domain Analogies`,requiredOutputItems:[`At least 2 patterns from other tools/frameworks/domains that apply to the question`,"For each: the external source (cite via `web_search` or `web_fetch` receipt) and\n  how it maps to our codebase",`One "missing pattern we should adopt" recommendation`],focusAreas:[`Ask: "What's the bigger opportunity everyone else is ignoring?"`,`Seek undervalued approaches and non-obvious connections across domains`,`Challenge narrow framing: "Is this really just an X problem, or is it also a Y problem?"`],variantSummary:"Your lens: cross-domain pattern matching + expansionist. Weight `web_search` + `web_fetch`\nhigher than peers. Assume the LLM's training data is stale — verify with fresh searches."}),Delta:n({description:`Research variant — implementation feasibility and performance implications`,lensName:`Executor`,lensDescription:`implementation feasibility`,lensPrompt:`focus on what can actually be built, the fastest path to value, and real-world constraints.`,identityIntro:`, a variant of the Researcher agent optimized for **implementation feasibility**. Focus on performance implications, scaling concerns, and concrete implementation paths. Ground theoretical proposals in practical reality.`,requiredOutputSection:`Implementation Cost & Feasibility`,requiredOutputItems:["Complexity snapshot: you MUST call `measure({ path })` on any file ≥ 50 LOC in the\n  target subsystem at least once and quote the `cognitiveComplexity` result","Blast radius estimate: `blast_radius({ changed_files })` on the proposed edits",`Time/risk table: | Change | Lines | Risk | Effort |`,`Feasibility verdict: SAFE / RISKY / INFEASIBLE with one-line justification`],focusAreas:[`Ask: "Can this actually be built? What's the fastest path to a working version?"`,`Ground every proposal in concrete effort: lines of code, files changed, risk`,`Reject elegant theory that can't survive contact with the codebase`],variantSummary:'Your lens: implementation feasibility + executor. Prefer `measure` + `blast_radius` +\n`analyze({ items: [{aspect: "patterns", ...}] })` over abstract reasoning.'})}},"Code-Reviewer":{title:`The Quality Guardian`,description:`Code review specialist analyzing code for quality, security, performance, and maintainability`,compactRole:`Dual-perspective code review`,argumentHint:`File path, PR, or code to review`,toolRole:`reviewer`,sharedBase:`code-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`,`layered-knowledge-operating-policy`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`typescript`,`When reviewing TypeScript code — type patterns, best practices`],[`lesson-learned`,`When review exposes a reusable engineering lesson`]],variants:{Alpha:r({roleName:`Code-Reviewer`,description:`Primary code reviewer`,lensName:`Compliance & Red-Team`,lensDescription:`compliance and red-teaming`,lensPrompt:`you hunt for correctness bugs, security holes, and contract violations that will break in production.`,identityIntro:`, the primary Code-Reviewer agent.`,focusAreas:[`**Correctness** — Logic errors, race conditions, null/undefined paths, off-by-one`,`**Security** — OWASP Top 10, input validation, secrets, injection vectors`,`**Contract compliance** — Does this honor its type signatures, API contracts, and invariants?`,`**Error handling** — What happens on the unhappy path? Missing try/catch, swallowed errors`],instinct:`Your instinct: "How does this break?" Think like an attacker and a pessimist.`,closing:`When in doubt, flag it — false positives are cheaper than missed bugs in production.`}),Beta:r({roleName:`Code-Reviewer`,description:`Code reviewer variant — different LLM perspective for dual review`,lensName:`Quality & Engineering Excellence`,lensDescription:`quality and engineering excellence`,lensPrompt:`you focus on maintainability, performance, testing, and whether the code will age well.`,identityIntro:`, the secondary Code-Reviewer agent.`,focusAreas:[`**Maintainability** — Naming clarity, single responsibility, cognitive complexity, DRY`,`**Performance** — N+1 queries, unnecessary allocations, missing caching, O(n²) where O(n) suffices`,`**Testing** — Coverage for new/changed logic, edge cases, test readability`,`**Patterns** — Consistency with existing codebase conventions, idiomatic usage`],instinct:`Your instinct: "Will a new team member understand this in 6 months?" Think like a mentor.`,closing:`Prefer actionable suggestions over vague concerns. Show the better version when possible.`})}},"Architect-Reviewer":{title:`The Structural Guardian`,description:`Reviews architecture for pattern adherence, SOLID compliance, dependency direction, and structural integrity`,compactRole:`Architecture review`,argumentHint:`Files, PR, or subsystem to architecture-review`,toolRole:`reviewer`,sharedBase:`architect-reviewer-base`,sharedProtocols:[`thinking-principles`,`review-principles`,`layered-knowledge-operating-policy`],category:`review`,skills:[[`aikit`,`**Always** — AI Kit tool signatures, search, analysis`],[`c4-architecture`,`When reviewing architectural diagrams or boundary changes`],[`adr-skill`,`When the review involves architecture decisions — reference or create ADRs`],[`docs`,`When architecture review should update durable documentation`]],extraBody:`You are **not** the Code-Reviewer agent. Code-Reviewer handles correctness, testing, security, and code quality. You handle the big picture: service boundaries, dependency direction, pattern adherence, and structural health.`,variants:{Alpha:r({roleName:`Architect-Reviewer`,description:`Primary architecture reviewer`,lensName:`Structural Prosecutor`,lensDescription:`structural prosecution`,lensPrompt:`you challenge architectural choices, find boundary violations, and test whether the design survives growth.`,identityIntro:`, the primary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Boundary violations** — Does this cross package/module boundaries it shouldn't?`,`**Dependency direction** — Are dependencies flowing inward? Any layer leakage?`,`**Hidden coupling** — Shared mutable state, implicit contracts, temporal coupling`,`**Scalability stress** — What breaks at 10x load, 10x data, 10x features?`],instinct:`Your instinct: "This design will fail when..." Challenge every architectural assumption.`,closing:`If a boundary is crossed, require justification or block.`}),Beta:r({roleName:`Architect-Reviewer`,description:`Architecture reviewer variant — different LLM perspective for dual review`,lensName:`Pragmatic Defense`,lensDescription:`pragmatic defense`,lensPrompt:`you evaluate whether the architecture is proportional to the problem, and defend reasonable trade-offs.`,identityIntro:`, the secondary Architect-Reviewer agent.`,focusHeading:`Your primary focus areas:`,focusAreas:[`**Proportionality** — Is the architecture proportional to the problem? Over-engineering is a defect.`,`**Trade-off validity** — Are the trade-offs explicitly acknowledged and reasonable?`,`**Migration path** — Can this evolve without a rewrite? Is there a clear upgrade path?`,`**Team ergonomics** — Can the team actually maintain this? Does it match their skills?`],instinct:`Your instinct: "Is this the simplest architecture that solves the actual problem?"`,closing:`Push back on unnecessary complexity. Defend working solutions against premature abstraction.`})}}};export{i as AGENTS};

package/scaffold/dist/definitions/bodies.mjs

@@ -26,6 +26,7 @@ When dispatching subagents, include this line: "Communication style: terse like
 
 ## Bootstrap
 1. status({ includePrelude: true }) -> onboard({ path: "." }) if needed.
+1a. For flow dispatch: status({ includePrelude: true }) → if onboard missing or workspace stale, onboard({ path: ".", update: true }) before any subagent dispatch.
 2. Apply layered knowledge protocol (see below).<!-- layered-header -->
 3. search({ query: "SESSION CHECKPOINT", origin: "curated" }) before planning.
 5. Load skills by trigger: aikit always; multi-agents-development before delegation; present before non-tiny output (check Transport section for preferBrowser); brainstorming for design decisions.
@@ -37,6 +38,30 @@ Critical: Standard + dual code review + architecture review + security review.
 
 Floor skips flow activation, evidence map, dual review, decision protocol. Standard+ uses them.
 
+Floor short-circuit: if changeManifest shows only NONE/COSMETIC (no STRUCTURAL/NEW/REMOVED), skip specialist dispatch entirely. Saves context + dispatch slot.
+
+## Flow-Aware Dispatch Classification
+
+### Flow Types
+Classify each flow to determine guard and re-onboard behavior:
+
+| Type | Examples | Guard fires? | Re-onboard after? |
+|------|----------|-------------|-------------------|
+| Read-only | Research, Analysis, Review | No | No |
+| Write | Implementation, Refactor, Fix | Yes | Yes |
+| Epilogue-only | Docs-sync, Lesson-learned | No | No |
+| Mixed | Orchestrator full cycle | Yes (on write steps only) | Yes |
+
+### Agent Dispatch Classification
+Classify each step by agent role:
+- **Read-only agents**: Explorer, Researcher*, Code-Reviewer*, Architect-Reviewer*, Planner, Documenter, Security
+- **Write-capable agents**: Implementer, Refactor, Frontend, Debugger (when fixing)
+
+For Mixed flows, each step inherits classification from its dispatched agent. Write-capable agents get \`readonly: false\`; all others \`readonly: true\`.
+
+### Pre-Dispatch Staleness Check
+Before dispatching a write-capable agent, run \`status({ includePrelude: true })\` to verify onboard freshness. If workspace structure changed since last onboard (new/deleted/modified files), run \`onboard({ path: ".", update: true })\` first. Read-only dispatches skip this check (0 token cost). The \`readonly\` flag is a contractual convention, not runtime enforcement — subagents retain full MCP tool access.
+
 ## Protocol Coverage Map
 - conversation-compression: before each dispatch batch, withdraw/profile context; after each batch, deposit status/files/decisions/blockers; never echo raw subagent output.
 - decision-protocol: Standard+ trade-off/design work gets independent research, synthesis verdict, recommendation, confidence, blind spots; Critical adds wider review.
@@ -75,12 +100,13 @@ Every \`runSubagent\` prompt includes all of:
  3. **Arch Context** — Pre-compress with AI Kit tools before including in prompt. pick by token budget: efficient → \`file_summary\` (T1=structure, T2=content), full → \`digest\`. Default efficient. **Never pass raw file contents — always compress first.** This eliminates subagent need for \`read_file\`.
 4. **Prior Knowledge** — \`knowledge({ action: "lesson", subAction: "list-lessons", topic: "<2-3 keywords>", minConfidence: 70 })\` + \`search({ query: "<task area>", category: "conventions", limit: 3 })\`. Include high-confidence results. Skip for Floor.
 5. **Artifacts Path** — active flow's run dir / artifacts path from \`flow({ action: 'status' })\`.
-6. **FORGE** — tier, task_id, evidence requirements. Reviewers add CRITICAL/HIGH claims into your task_id; never create their own.
+6. **FORGE** — tier (from forge_classify), task_id, evidence requirements. Pass tier directly; Documenter/SKILL.md maps tier to docs generation depth internally. Reviewers add CRITICAL/HIGH claims into your task_id; never create their own.
 7. **Flow Context** — "Call \`knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>', budget: 6000 })\` as your FIRST action. Reuse withdrawn refs and L0 card refs before broad retrieval. Do NOT independently reload workspace-core or architecture cards when dispatch already carries applicable refs."
  8. ${a().replace(/\n/g,`
     `)}
  9. **Self-Review** — checklist before declaring status: scope respected? tests pass? conventions followed?
  10. **Return contract** — \`DONE\` | \`DONE_WITH_CONCERNS\` | \`NEEDS_CONTEXT\` | \`BLOCKED\`. ≤200 words: status, files, decisions. Full detail only if BLOCKED.
+ 11. **Read-Only Mode** — \`readonly: true|false\`. Controls whether agent may modify files. Derived from flow type + step classification. Write-capable agents (Implementer, Refactor, Frontend, Debugger) receive \`false\`; all others \`true\`. Contractual convention — no runtime enforcement.
 
 Always pass \`agentName\`. Missing/empty is a dispatch bug.
 
@@ -107,6 +133,7 @@ ${r({audience:`agent`})}
 ## Evidence + Validation
 Use forge_classify for tier. Standard+ creates one Orchestrator-owned evidence_map task_id; reviewers add CRITICAL/HIGH claims into it; only Orchestrator runs gate.
 After implementation batches: check({}) + test_run({}) once, then blast_radius for shared/public changes.
+After write flow completion: onboard({ path, update: true }) → reindex({}) → produce_knowledge({}) to sync L0 cards and vector index. Verify with status({}). Read-only/Epilogue-only flows skip (0 token cost). If re-onboard fails, log warning and surface in flow status — do not block.
 
 ## Presentation
 Use present for summaries, reports, evidence maps, task plans, batch results, verdicts, progress, reviews, approval gates. Plain chat only for <=2 short status sentences or one simple question.
@@ -125,8 +152,9 @@ Use present for summaries, reports, evidence maps, task plans, batch results, ve
 Use web_fetch/http first. On auth failure, load repo-access; if exhausted, use AI Kit browser. Do not use system browser for agent-visible verification.
 
 ## End
-- reindex after structural changes; produce_knowledge for durable updates; remember non-trivial decisions.
-- L0 card maintenance: changed topics after flow completion schedule L0 card regeneration via \`briefing-card-compiler\`.
+- After write flows: onboard({ path, update: true }) → reindex({}) → produce_knowledge({}). L0 card regen via \`briefing-card-compiler\` if structural change detected.
+- After read-only/epilogue-only flows: no reindex (0 token cost). remember decisions as normal.
+- If re-onboard/reindex fails: log warning, surface in flow status, do not block.
 - Flow-derived promotion: evidence-backed promotion candidates from final consolidation; confidence alone never promotes.
 - session_digest({ persist: true }).`,Planner:`${i()}
 
@@ -462,9 +490,26 @@ After shared bootstrap, run \`search({ query: "security vulnerabilities conventi
 
 > **Reminder:** Follow ## MANDATORY FIRST ACTION from your shared base protocol.
 
+## Tier Composition: Evidence × Docs Generation
+
+Two independent tier dimensions compose: **evidence protocol** (who you report to) and **docs generation** (what you produce). Both use the same FORGE \`tier\` value, but govern different behaviors.
+
+| Tier | Evidence Protocol | Docs Generation | Short-circuit Gate |
+|------|------------------|----------------|-------------------|
+| Floor | file:line citations only. No \`evidence_map\`. | State tracking only. Skip generation. See SKILL.md ┬╗ Tier Branch Table. | Orchestrator may skip dispatch if changeManifest = NONE/COSMETIC only |
+| Standard | Add 2-4 CRITICAL/HIGH findings with receipts. | Surgical: regenerate only affected docs + cross-ref validation. | N/A — dispatch always runs |
+| Critical | All CRITICAL/HIGH findings; tag contract/security claims with \`safety_gate\`. | Full Phase 1-7 + phases matching change type. | N/A — dispatch always runs |
+
+**Docs generation branching is defined in SKILL.md ┬╗ Tier Branching — not duplicated here.** This file controls evidence protocol only.
+
 ## Documentation Protocol
 
 1. **AI Kit Recall** — \`search({ query: "documentation <area>" })\` + \`knowledge({ action: "list" })\`
+1a. **Freshness check** (E4 Knowledge↔Docs Bridge): After recall, check L2 lessons against existing docs for staleness. Session-level dedup per topic.
+    - \`search({ query: "recent lessons about <target domain>" })\`
+    - \`knowledge({ action: 'lesson', subAction: 'list-lessons', topic: '<target domain>' })\`
+    - If any \`lesson.updatedAt > doc._lastSynced.syncedAt\`: emit \`[FRESHNESS WARNING]\` in output
+    - Run BEFORE Analyze step so freshness signals inform evidence gathering
 2. **Analyze** — \`analyze({ items: [{aspect: "structure", ...}] })\`, \`analyze({ items: [{aspect: "entry_points", ...}] })\`, \`file_summary({ files, tier: 'T1' })\`
 3. **Draft** — write docs following project conventions
 4. **Cross-reference** — link related docs, keep consistency

package/scaffold/dist/definitions/skills/c4-architecture.mjs

@@ -139,7 +139,29 @@ Default: Context + Container. Add Component only for a complex container and a c
 
 1. **Study examples first**: Load references/ example files to understand visual patterns, label density, and layout conventions before generating.
 2. Identify audience and decision the diagram supports.
-3. Gather evidence with AI Kit: analyze/graph/search/file_summary.
+3. **Gather evidence with AI Kit - check onboard cache FIRST:**
+   a. **Check onboard cache:**
+      - Run status({ includePrelude: true }) - if workspaceCore shows onboard data available:
+        - Read cache from ~/.aikit/workspaces/<hash>/onboard/:
+          - structure.md - module tree, layers, directory shape
+          - dependencies.md - internal/external dependency graph
+          - symbols.md - exported symbols, type signatures
+          - entry-points.md - API surface, CLI entry points
+        - Freshness: cache fresh if status().onboarded == true and index recent.
+          For finer control: compare git diff --stat pending change count.
+          Default: <50 pending changes -> serve from cache | >=50 -> refresh.
+   b. **Use cache data for C4:**
+      - Extract layers from structure analysis (layer-detector classifications)
+      - Extract modules/containers from directory tree
+      - Extract dependency arrows from cross-module imports
+      - Identify external systems from external dependency listing
+   c. **Fallback (if cache missing or stale):**
+      - analyze({ items: [{aspect: "structure"}, {aspect: "dependencies"}, {aspect: "entry_points"}] })
+      - 3 aspects instead of 6 - symbols + patterns + diagram aspects add cost but not essential for C4 topology
+   d. **Supplementary context (always runs):**
+      - graph({ action: find_nodes, name_pattern: <system> }) for relationship graph
+      - search({ query: <system> technology stack }) for tech details
+      - file_summary({ files, tier: T1 }) for individual file structure when needed
 4. Pick level(s); avoid mixing levels in one diagram.
 5. **Generate structured diagram JSON** conforming to the centralized diagram schema (see ~/.aikit/resources/renderers/schemas/). Render via CLI:
 

package/scaffold/dist/definitions/skills/docs.mjs

@@ -181,7 +181,7 @@ Use Phase 1 tool outputs to answer questions for each of the seven documents. Ru
 | conventions.md | \`analyze({ items: [{aspect: "patterns", ...}] })\` → naming, formatting; \`search({ query: "conventions" })\` → detected conventions |
 | integrations.md | \`analyze({ items: [{aspect: "dependencies", ...}] })\` → external deps; \`search({ query: "API\\|database\\|auth\\|webhook" })\` → integration points |
 | testing.md | \`analyze({ items: [{aspect: "patterns", ...}] })\` → test patterns; \`search({ query: "test framework" })\` → test setup; \`test_run({})\` → test health |
-| concerns.md | \`audit({ path: "." })\` → health issues; \`dead_symbols({})\` → dead code; \`git_context({})\` → high-churn files |
+| concerns.md | \`audit({ path: "." })\` → health issues; \`dead_symbols({})\` → dead code; \`git_context({})\` → high-churn files; freshness check (Step 1a) before data gathering |
 
 ### Phase 3: Populate Documents
 
@@ -776,9 +776,12 @@ Use this template for any generated section that includes factual claims:
 Committed state file for incremental documentation updates. L0 regeneratable cache,
 committed to git so clones have warm cache.
 
+**Design: extends existing schema (backward compatible).** NO parallel \`_lastSynced\` block.
+Adds \`signatureHash\`, \`contractHash\` (optional), and \`syncedAt\` to the existing \`sourceFiles[path]\` entry.
+
 \`\`\`json
 {
-  "version": "1.0",
+  "version": "1.1",
   "layer": "l0",
   "timestamp": "ISO-8601",
   "lastCommitSha": "git rev-parse HEAD of last documented commit",
@@ -793,7 +796,10 @@ committed to git so clones have warm cache.
     "src/auth/login.ts": {
       "contentHash": "sha256-abc...",
       "signatures": ["login(credentials: Credentials): Promise<Session>"],
-      "changeClass": "NONE|COSMETIC|STRUCTURAL|NEW|REMOVED"
+      "signatureHash": "sha256-of-signatures-array",
+      "contractHash": "sha256-of-function-body+jsdoc",
+      "changeClass": "NONE|COSMETIC|STRUCTURAL|CONTRACT_CHANGE|NEW|REMOVED",
+      "syncedAt": "2026-06-22T12:00:00Z"
     }
   },
 
@@ -807,6 +813,28 @@ committed to git so clones have warm cache.
 }
 \`\`\`
 
+### Per-Doc Frontmatter (minimal \`_lastSynced\`)
+
+For each generated doc, include a lightweight frontmatter with only the fields LLMs consume:
+
+\`\`\`yaml
+---
+_lastSynced:
+  sourceHash: sha256-abc...
+  syncedAt: "2026-06-22T12:00:00Z"
+_generation:
+  tier: standard
+  trigger: signature-change
+  changeClass: STRUCTURAL
+---
+\`\`\`
+
+- \`sourceHash\` — LLM can compare against current code hash to detect staleness
+- \`syncedAt\` — LLM can assess freshness relative to knowledge cutoff
+- \`_generation\` block — provides provenance for LLM context awareness
+- Full state fields (\`signatureHash\`, \`contractHash\`) stay in \`.docs-state.json\` only
+- Avoids 375-500 token per-run cost of duplicating full state in frontmatter
+
 ### Release Notes Template (\`docs/releases/v{version}.md\`)
 
 \`\`\`markdown
@@ -1706,10 +1734,59 @@ Step 1: Check \`docs/.docs-state.json\` (the Committed Docs IR):
 - If present: compare \`lastCommitSha\` vs \`git rev-parse HEAD\`
   - SHA + onboardRef fresh → IR is fresh, use as-is (no re-run)
   - Stale → re-run \`onboard({update:true})\`, recompute change manifest, update IR
-- Change classification per file:
-  - Hash identical → NONE | New → NEW | Removed → REMOVED
-  - Hash diff, sigs match → COSMETIC (via \`analyze({ items: [{aspect: "symbols", path: "."}] })\`)
-  - Hash diff, sigs diff → STRUCTURAL
+
+Step 2: Compute current fingerprints (deterministic pre-step, not LLM work):
+- For each source file in scope:
+  - Skip binary files: \`.png\`, \`.jpg\`, \`.ico\`, \`.gif\`, \`.svg\`, \`.woff\`, \`.woff2\`, \`.eot\`, \`.ttf\`, \`.ico\`
+  - Compute \`contentHash\` via \`git hash-object <file>\` (preferred — no LLM context needed) or \`aikit_encode({ operation: 'sha256', input: readFile })\` (fallback)
+  - Extract signatures via tier-appropriate method:
+    - **Floor tier**: regex-based (cheap, fast-path) — \`/(?:export\\s+)?(?:default\\s+)?(?:async\\s+)?(?:function\\s+(\\w+)|(?:const|let|var)\\s+(\\w+)\\s*[=(:]|class\\s+(\\w+)|interface\\s+(\\w+)|type\\s+(\\w+)|abstract\\s+class\\s+(\\w+))/gm\`
+    - **Standard/Critical**: AST-based via \`analyze({ items: [{aspect: "symbols", path: "<file>"}] })\` — higher accuracy, catches re-exports, decorators, complex signatures
+  - Filter signatures to exported-only (non-exported symbols don't affect public API docs)
+
+Step 3: Classify Change per file:
+- File NOT in priorState → \`NEW\`
+- File in priorState but NOT on disk (ENOENT) → \`REMOVED\` (catch before hashing)
+- Hash identical, sigs match → \`NONE\`
+- Hash changed, sigs match → \`COSMETIC\` (content changed but public API unchanged)
+- Hash changed, exported sigs differ → \`STRUCTURAL\` (public API changed — requires doc update)
+- Hash changed, exported sigs same but contract markers changed → \`CONTRACT_CHANGE\` (behavior changed, sigs same — see note below)
+
+**Edge case: changed implementation, same signature.**
+A function's body may change (bug fix, perf optimization, new error handling) while its signature stays identical. The algorithm classifies this as COSMETIC, but docs describing behavior, preconditions, postconditions, or error states ARE stale. Mitigation:
+- Track \`contractHash\` — hash of function body + JSDoc/comments (optional, Standard/Critical only)
+- If \`contractHash\` differs but sigs match → flag as \`CONTRACT_CHANGE\` for human review
+- Known blind spot: this is not perfect. Documented as deferred improvement.
+
+Step 4: Special Triggers (run before final classification):
+- Config files (\`package.json\`, \`tsconfig.json\`, \`biome.json\`) → always \`STRUCTURAL\` regardless of hash/sig analysis
+- CI/CD config (\`.github/\`, \`.gitlab-ci.yml\`) → always \`STRUCTURAL\`
+- Removed files → \`REMOVED\` (ensure dependent docs are flagged)
+
+Step 5: Output changeManifest:
+\`\`\`json
+{
+  "files": {
+    "src/auth/login.ts": {
+      "changeClass": "STRUCTURAL",
+      "contentHash": "abc...",
+      "signatureHash": "def...",
+      "contractHash": "ghi...",
+      "syncedAt": "2026-06-22T12:00:00Z"
+    }
+  },
+  "summary": {
+    "none": 42,
+    "cosmetic": 3,
+    "structural": 1,
+    "contractChange": 0,
+    "new": 2,
+    "removed": 1,
+    "totalChanged": 7
+  },
+  "needsDocUpdate": true
+}
+\`\`\`
 
 Step 2: Doc inventory (always runs, not cached):
 - \`find({ glob: "docs/**/*.md" })\` — doc inventory
@@ -1720,9 +1797,9 @@ The IR (\`docs/.docs-state.json\`) stores:
 - \`version\` + \`layer: "l0"\` (regeneratable cache, not curated; committed to git)
 - \`lastCommitSha\` (committed = warm clones, no cold starts)
 - \`onboardRef\` (pointer to onboard cache, NO duplicated analysis data)
-- \`sourceFiles\` (per-file contentHash, signatures, changeClass)
-- \`docReverseIndex\` (schema reserved for E3 blast_radius integration)
-- \`_concurrency.version\` (compare-and-swap for multi-session safety)
+- \`sourceFiles\` (per-file contentHash, signatureHash, contractHash, syncedAt, changeClass)
+- \`docReverseIndex\` (schema reserved for E3 blast_radius integration — required for Standard tier)
+- \`_concurrency.version\` (compare-and-saw for multi-session safety, implement atomic write via write+rename)
 
 **Consumer pattern (all later phases):**
 - If IR fresh: read changeManifest + onboard cache, skip fresh analyze()
@@ -2017,6 +2094,16 @@ find({ pattern: "orgId|tenantId|teamId|workspaceId" })
 3. Cross-reference tour steps with actual files
 4. check({}) to ensure no build breaks
 5. Verify all interactive HTML files open correctly and contain valid JSON data
+
+# Cross-reference validation (Standard tier — R7)
+# Validate references FROM unchanged docs TO changed docs
+# Without this, doc A mentioning component B becomes stale when B is regenerated
+6a. blast_radius({ files: regeneratedDocFiles }) → find docs affected by regenerated content
+6b. For each affected doc:
+    - Check internal links to regenerated docs still resolve
+    - Verify code references (file:line) still exist
+    - Flag stale refs with ⚠️ Needs review — do NOT regenerate unchanged docs automatically
+6c. Store updated reference map in .docs-state.json
 \`\`\`
 
 #### SBC Completeness Scoring Detail
@@ -3224,6 +3311,46 @@ L3 (Evidence Archive) ──→ docs/reference/ — Verified claims with tool re
 4. Generate doc with evidence annotations (✓ verified / 🔍 inferred / ⚠ assumed)
 5. Promote verified claims as candidate L2 entries
 
+## Tier Branching (FORGE-aware)
+
+Docs generation depth is driven by FORGE tier (passed as \`tier\` from Orchestrator). This is the single source of truth — Documenter.md cross-references here.
+
+### Step 0: Check docs_tier
+- Read \`tier\` from dispatch envelope (maps directly from FORGE classification)
+- \`docs_tier\` = FORGE \`tier\` — always 1:1 by default
+- Override only when Orchestrator explicitly passes \`tierOverride\`
+
+### Tier Branch Table
+
+| Tier | Pipeline Execution | Fingerprinting | Evidence Protocol | Output |
+|------|-------------------|---------------|-------------------|--------|
+| Floor | Skip entirely | State tracking only (deterministic pre-step, not LLM) | file:line citations only | "No documentation updates needed" + state one-liner: \`state: { filesTracked, filesChanged, docsCurrent }\` |
+| Standard | Surgical: changed docs only + cross-ref validation | Change classification (AST-based for accuracy) | Add 2-4 CRITICAL/HIGH findings | Affected docs regenerated with \`_generation: { tier, trigger, changeClass }\` frontmatter |
+| Critical | Full Phase 1-7 (plus any phases matching change type) | Staleness tracking | All CRITICAL/HIGH + safety_gate | Full 7 docs + C4 + tours + interactive companions |
+
+**Note:** Standard tier requires E3 \`docReverseIndex\` for doc-to-file mapping — blocked until E3 ships. Without E3, Standard falls back to heuristic (file path matching + \`find\` glob).
+
+### Cross-Reference Validation (Standard tier)
+
+When Standard tier regenerates specific docs, validate references from ALL docs (not just changed ones):
+1. \`blast_radius({ files: regeneratedDocFiles })\` → find docs that reference changed content
+2. For each affected doc: check internal links resolve, verify code references still exist
+3. Flag stale references with \`⚠️ Needs review\` banner — do NOT regenerate unchanged docs automatically
+4. Store updated reference map in \`.docs-state.json\`
+
+### Doc-Type Sensitivity
+
+Not all doc types need the same tier. When change classification detects signature/STRUCTURAL changes, auto-escalate Reference docs to Critical-tier regeneration:
+
+| Change Type | Minimum Docs Tier |
+|-------------|------------------|
+| Signature/API change (STRUCTURAL) | Critical (for Reference docs) |
+| Content change (COSMETIC) | Standard |
+| Configuration/package change | Critical (always STRUCTURAL) |
+| New file/module | Standard |
+| Internal refactor (no public API change) | Floor |
+| Comment/whitespace only | Floor |
+
 ## Scenario Detection
 
 | Condition | Mode |
@@ -3236,15 +3363,27 @@ L3 (Evidence Archive) ──→ docs/reference/ — Verified claims with tool re
 
 ## Workflow
 
+0. **Check docs_tier** — Read FORGE \`tier\` from dispatch. Map to Tier Branch Table above. Floor tier → skip to step 9 (state tracking only).
 1. **Study existing documentation first**: Load reference examples from references/ directory and existing project docs/ to understand conventions, tone, and structure before generating new content.
+1a. **Freshness check** (Knowledge↔Docs Bridge): Before loading layered context, check if recent L2 lessons contradict studied docs. Session-level dedup (checked topic Set) prevents repeat checks:
+    - \`search({ query: "recent lessons about <target domain>" })\`
+    - \`knowledge({ action: 'lesson', subAction: 'list-lessons', topic: '<target domain>' })\`
+    - For each lesson found: if \`lesson.updatedAt > doc._lastSynced.syncedAt\`:
+      Flag: \`[FRESHNESS WARNING] Knowledge entry "<title>" updated <date>, may affect <doc path>\`
+    - If \`syncedAt\` missing on doc → treat as stale (conservative), emit warning
+    - If no recent lessons match → continue silently
+    - Session dedup: maintain \`Set<string>\` of checked topic+entry IDs per session; skip if already checked
 2. **Load layered context**: \`status({ includePrelude: true })\` → L0. \`knowledge({ action: 'withdraw', scope: 'flow', profile: 'documenter', budget: 6000 })\` → L1.
 3. Gather intent/evidence from flow artifacts, git diff, blast_radius, produce_knowledge, analyze, changelog, or search.
 4. Classify target docs with Diataxis or extended doc type table.
 5. Map changed capability to doc action.
-6. Generate/update surgically; preserve valid human text.
+6. Generate/update surgically; preserve valid human text. Branch by tier:
+   - **Floor**: Skip generation. Update \`.docs-state.json\` hashes only. Emit \`state: { filesTracked, filesChanged, docsCurrent }\`.
+   - **Standard**: Generate/update only affected docs + cross-ref validation (see Cross-Reference Validation section).
+   - **Critical**: Full regeneration — execute applicable pipeline phases.
 7. **Generate interactive companions**: C4 viewers, tour viewers, present dashboards.
 8. Validate claims, links, references, and generated assets. Use \`browser\` to screenshots.
-9. If nothing durable changed, report: "No documentation updates needed."
+9. If nothing durable changed (or Floor tier), report: "No documentation updates needed."
 
 ## Change -> Doc Action
 

package/packages/server/dist/prelude-DpX0QnqF.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{n as e,t}from"./server-BtRv0mbH.js";export{t as buildPreludeInjection,e as generatePrelude};

package/packages/server/dist/prelude-pJPHXvnQ.js

@@ -1 +0,0 @@
-import{n as e,t}from"./server-BYZo2XjK.js";export{t as buildPreludeInjection,e as generatePrelude};

package/packages/server/dist/sampling-9GcILoHr.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import{r as e}from"./server-BtRv0mbH.js";export{e as createSamplingClient};

package/packages/server/dist/sampling-DuXB6-rK.js

@@ -1 +0,0 @@
-import{r as e}from"./server-BYZo2XjK.js";export{e as createSamplingClient};