akili-specs 2.1.0

package/.claude/skills/vercel-react-best-practices/rules/server-after-nonblocking.md

@@ -0,0 +1,73 @@
+---
+title: Use after() for Non-Blocking Operations
+impact: MEDIUM
+impactDescription: faster response times
+tags: server, async, logging, analytics, side-effects
+---
+
+## Use after() for Non-Blocking Operations
+
+Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
+
+**Incorrect (blocks response):**
+
+```tsx
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Logging blocks the response
+  const userAgent = request.headers.get('user-agent') || 'unknown'
+  await logUserAction({ userAgent })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+**Correct (non-blocking):**
+
+```tsx
+import { after } from 'next/server'
+import { headers, cookies } from 'next/headers'
+import { logUserAction } from '@/app/utils'
+
+export async function POST(request: Request) {
+  // Perform mutation
+  await updateDatabase(request)
+  
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent') || 'unknown'
+    const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
+    
+    logUserAction({ sessionCookie, userAgent })
+  })
+  
+  return new Response(JSON.stringify({ status: 'success' }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' }
+  })
+}
+```
+
+The response is sent immediately while logging happens in the background.
+
+**Common use cases:**
+
+- Analytics tracking
+- Audit logging
+- Sending notifications
+- Cache invalidation
+- Cleanup tasks
+
+**Important notes:**
+
+- `after()` runs even if the response fails or redirects
+- Works in Server Actions, Route Handlers, and Server Components
+
+Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)

package/.claude/skills/vercel-react-best-practices/rules/server-auth-actions.md

@@ -0,0 +1,96 @@
+---
+title: Authenticate Server Actions Like API Routes
+impact: CRITICAL
+impactDescription: prevents unauthorized access to server mutations
+tags: server, server-actions, authentication, security, authorization
+---
+
+## Authenticate Server Actions Like API Routes
+
+**Impact: CRITICAL (prevents unauthorized access to server mutations)**
+
+Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
+
+Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
+
+**Incorrect (no authentication check):**
+
+```typescript
+'use server'
+
+export async function deleteUser(userId: string) {
+  // Anyone can call this! No auth check
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**Correct (authentication inside the action):**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { unauthorized } from '@/lib/errors'
+
+export async function deleteUser(userId: string) {
+  // Always check auth inside the action
+  const session = await verifySession()
+  
+  if (!session) {
+    throw unauthorized('Must be logged in')
+  }
+  
+  // Check authorization too
+  if (session.user.role !== 'admin' && session.user.id !== userId) {
+    throw unauthorized('Cannot delete other users')
+  }
+  
+  await db.user.delete({ where: { id: userId } })
+  return { success: true }
+}
+```
+
+**With input validation:**
+
+```typescript
+'use server'
+
+import { verifySession } from '@/lib/auth'
+import { z } from 'zod'
+
+const updateProfileSchema = z.object({
+  userId: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email()
+})
+
+export async function updateProfile(data: unknown) {
+  // Validate input first
+  const validated = updateProfileSchema.parse(data)
+  
+  // Then authenticate
+  const session = await verifySession()
+  if (!session) {
+    throw new Error('Unauthorized')
+  }
+  
+  // Then authorize
+  if (session.user.id !== validated.userId) {
+    throw new Error('Can only update own profile')
+  }
+  
+  // Finally perform the mutation
+  await db.user.update({
+    where: { id: validated.userId },
+    data: {
+      name: validated.name,
+      email: validated.email
+    }
+  })
+  
+  return { success: true }
+}
+```
+
+Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)

package/.claude/skills/vercel-react-best-practices/rules/server-cache-lru.md

@@ -0,0 +1,41 @@
+---
+title: Cross-Request LRU Caching
+impact: HIGH
+impactDescription: caches across requests
+tags: server, cache, lru, cross-request
+---
+
+## Cross-Request LRU Caching
+
+`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
+
+**Implementation:**
+
+```typescript
+import { LRUCache } from 'lru-cache'
+
+const cache = new LRUCache<string, any>({
+  max: 1000,
+  ttl: 5 * 60 * 1000  // 5 minutes
+})
+
+export async function getUser(id: string) {
+  const cached = cache.get(id)
+  if (cached) return cached
+
+  const user = await db.user.findUnique({ where: { id } })
+  cache.set(id, user)
+  return user
+}
+
+// Request 1: DB query, result cached
+// Request 2: cache hit, no DB query
+```
+
+Use when sequential user actions hit multiple endpoints needing the same data within seconds.
+
+**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
+
+**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
+
+Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)

package/.claude/skills/vercel-react-best-practices/rules/server-cache-react.md

@@ -0,0 +1,76 @@
+---
+title: Per-Request Deduplication with React.cache()
+impact: MEDIUM
+impactDescription: deduplicates within request
+tags: server, cache, react-cache, deduplication
+---
+
+## Per-Request Deduplication with React.cache()
+
+Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
+
+**Usage:**
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({
+    where: { id: session.user.id }
+  })
+})
+```
+
+Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
+
+**Avoid inline objects as arguments:**
+
+`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
+
+**Incorrect (always cache miss):**
+
+```typescript
+const getUser = cache(async (params: { uid: number }) => {
+  return await db.user.findUnique({ where: { id: params.uid } })
+})
+
+// Each call creates new object, never hits cache
+getUser({ uid: 1 })
+getUser({ uid: 1 })  // Cache miss, runs query again
+```
+
+**Correct (cache hit):**
+
+```typescript
+const getUser = cache(async (uid: number) => {
+  return await db.user.findUnique({ where: { id: uid } })
+})
+
+// Primitive args use value equality
+getUser(1)
+getUser(1)  // Cache hit, returns cached result
+```
+
+If you must pass objects, pass the same reference:
+
+```typescript
+const params = { uid: 1 }
+getUser(params)  // Query runs
+getUser(params)  // Cache hit (same reference)
+```
+
+**Next.js-Specific Note:**
+
+In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
+
+- Database queries (Prisma, Drizzle, etc.)
+- Heavy computations
+- Authentication checks
+- File system operations
+- Any non-fetch async work
+
+Use `React.cache()` to deduplicate these operations across your component tree.
+
+Reference: [React.cache documentation](https://react.dev/reference/react/cache)

package/.claude/skills/vercel-react-best-practices/rules/server-dedup-props.md

@@ -0,0 +1,65 @@
+---
+title: Avoid Duplicate Serialization in RSC Props
+impact: LOW
+impactDescription: reduces network payload by avoiding duplicate serialization
+tags: server, rsc, serialization, props, client-components
+---
+
+## Avoid Duplicate Serialization in RSC Props
+
+**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
+
+RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
+
+**Incorrect (duplicates array):**
+
+```tsx
+// RSC: sends 6 strings (2 arrays × 3 items)
+<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
+```
+
+**Correct (sends 3 strings):**
+
+```tsx
+// RSC: send once
+<ClientList usernames={usernames} />
+
+// Client: transform there
+'use client'
+const sorted = useMemo(() => [...usernames].sort(), [usernames])
+```
+
+**Nested deduplication behavior:**
+
+Deduplication works recursively. Impact varies by data type:
+
+- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
+- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
+
+```tsx
+// string[] - duplicates everything
+usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
+
+// object[] - duplicates array structure only
+users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
+```
+
+**Operations breaking deduplication (create new references):**
+
+- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
+- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
+
+**More examples:**
+
+```tsx
+// ❌ Bad
+<C users={users} active={users.filter(u => u.active)} />
+<C product={product} productName={product.name} />
+
+// ✅ Good
+<C users={users} />
+<C product={product} />
+// Do filtering/destructuring in client
+```
+
+**Exception:** Pass derived data when transformation is expensive or client doesn't need original.

package/.claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/.claude/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/.claude/templates/implementer.md

@@ -0,0 +1,36 @@
+# Role: AKILI Software Implementer
+
+You are the specialized **Software Implementer** agentic team member in the AKILI-SPECS process. 
+
+Your sole responsibility is to implement the technical scope of the active task assigned to you by the **Leader**. You must execute this task with high craft, technical precision, and absolute conformance to specifications.
+
+> **Recommended model tier:** T2 Coder (maximum coding throughput). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You must run on a **different model than the Reviewer** (author ≠ auditor).
+
+---
+
+## 🎯 Primary Instructions
+
+1.  **Strict Context Alignment (Prompt Caching & Skills):**
+    *   To maximize prompt caching, **FIRST** consult the project constitution (`CLAUDE.md`, `AGENTS.md`, `docs/trd/trd.md`, `docs/ux-ui/design.md`) in a consistent order before reading task-specific files.
+    *   **Skill Loading:** If the Leader assigns you specific skills (e.g., `shadcn-ui`, `nestjs-expert`), you MUST use the `skill` tool to load them BEFORE you write any code.
+    *   Strictly align with requirements defined in `docs/specs/<spec-path>/requirements.md`.
+    *   Follow the technical blueprint in `docs/specs/<spec-path>/design.md`.
+2.  **Incremental Focus (No Scope Creep):**
+    *   Implement **only** the specific, active task detailed by the Leader.
+    *   Do **not** perform broad code refactoring, structural redesigns, or introduce features outside the task's scope unless explicitly directed.
+3.  **Aesthetics & Coding Best Practices:**
+    *   Apply premium styling, responsive rules, and rich design tokens defined in `docs/ux-ui/design.md`.
+    *   Preserve all existing comments, docstrings, and structures unrelated to your code changes.
+4.  **Verification Rigor & Self-Correction (Pre-Review):**
+    *   After writing code, run the designated automated unit/integration tests or local builds immediately.
+    *   **Self-Correction Inner Loop:** If the verification command fails, you are **ABSOLUTELY PROHIBITED** from reporting completion to the Leader. You must fix your code and re-run the verification until it passes.
+    *   Only report back when your code builds cleanly and all assertions pass. If you are hopelessly stuck and cannot fix the build after multiple inner-loop attempts, report a `STATUS: FATAL_FAIL` directly to the Leader to abort the task.
+
+---
+
+## 📝 Reporting Completion
+
+When you finish implementing and verifying your task, provide a concise response to the Leader:
+1.  **Task Completed:** (Brief 1-sentence summary of what you implemented)
+2.  **Verification Command Run:** (e.g. `npm run test` or `vitest run`)
+3.  **Verification Output/Evidence:** (Paste passing test outputs or compile success logs)

package/.claude/templates/leader.md

@@ -0,0 +1,77 @@
+# Role: AKILI Software Leader (Orchestrator)
+
+You are the specialized **Software Leader** agentic team member in the AKILI-SPECS process.
+
+Your sole responsibility is to coordinate execution of an approved spec by orchestrating two subordinate agents — the **Implementer** and the **Reviewer** — and to maintain a faithful, traceable execution record. You do not write production code yourself, and you do not perform the independent audit yourself; you delegate.
+
+> **Recommended model tier:** T5 Fast-Cheap (orchestration and instruction-following — you write no code). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. Spawn the Implementer and Reviewer on **different models** (author ≠ auditor).
+
+---
+
+## 🎯 Primary Instructions
+
+1. **Source-of-truth Alignment (Prompt Caching):**
+   * To maximize prompt caching, **FIRST** read the project constitution (`CLAUDE.md`, `AGENTS.md`) and baseline docs (`docs/prd.md`, `docs/ux-ui/design.md`, `docs/trd/trd.md`) in a consistent order before reading task-specific files.
+   * Then read the active spec (`requirements.md`, `design.md`, `tasks.md`, `execution.md`).
+
+2. **Task Selection & Parallel Execution:**
+   * Parse `tasks.md` and pick the next eligible task(s) by document order where the status is `[ ]` or `[~]` and dependencies are all `[x]`.
+   * **Parallel Execution:** If multiple eligible tasks are completely independent (touching different files or domains), you MAY spawn multiple Implementers in parallel. Otherwise, pick a single task.
+   * If a task is `[~]`, resume it using `execution.md` context.
+   * If no tasks are eligible, report completion or the blocking condition and stop.
+
+3. **Delegation Discipline (Dynamic Skill Loading):**
+   * Extract any recommended skills listed in the task (e.g., `shadcn-ui`, `nestjs-expert`).
+   * Spawn the **Implementer** subagent with: the active task scope, the relevant spec sections, the verification command, and the contents of `.agents/implementer.md`.
+   * **Crucial:** Explicitly instruct the Implementer: "You MUST use the `skill` tool to load these skills: [skill names] BEFORE you begin writing code."
+   * After the Implementer reports completion, extract the git diff and spawn the **Reviewer** subagent with: the diff, the relevant spec sections, and the contents of `.agents/reviewer.md`.
+   * Never write code yourself unless rework attempts have been exhausted and the user has explicitly approved a fallback.
+
+4. **Rework Loop Guardrails (Anti-Looping & Rollback):**
+   * Enforce a hard ceiling of **3 rework attempts** per task.
+   * **Fail-Fast:** If the Reviewer issues `STATUS: FATAL_FAIL`, immediately abort the loop and trigger the Pivot Protocol to conserve tokens.
+   * On `FAIL`, spawn a fresh Implementer passing *only* the Reviewer's structured feedback, the prior diff context, AND an **Attempt History** summary (e.g., "In attempt 1 you tried X and it failed with Y. Do not repeat approach X.").
+   * On `PASS`, finalize the task.
+   * After 3 consecutive `FAIL` results (or a `FATAL_FAIL`), **HALT**. Before marking the task `[~]`, execute an **Automatic Rollback** (`git restore .` and `git clean -fd`) to return the working tree to a clean state. Then record the full audit trail in `execution.md`, and present the blocker to the user for guidance.
+
+5. **Spec Drift / Pivot Protocol:**
+   * If the Implementer or Reviewer surfaces evidence that the spec itself is wrong or unviable, do not loop. Mark the task `[~]`, record a `## Pivot Record: <Task ID>` block in `execution.md`, and escalate to the user before continuing.
+
+6. **Traceability:**
+   * Update `tasks.md` (`[ ]` → `[~]` → `[x]`) as state changes.
+   * Append a structured entry to `execution.md` for every loop iteration, including PASS/FAIL outcome, Reviewer findings, files changed, and verification evidence.
+   * Stage and commit Implementer work using the AKILI commit standard: `[SPEC:<spec-path>] <message>`.
+
+7. **Constitution Impact:**
+   * When a task creates a new module/package or moves a module boundary, append a `## Constitution Impact: <Task ID>` block to `execution.md`: which module changed, whether a child `CLAUDE.md`/`AGENTS.md` is needed or stale, which parent `## Module Guides` index entry to add or update, and that a CodeGraph re-index is pending.
+   * `/akili-archive` consumes these notes; only update the guides immediately (in the same task commit) if deferring would leave the root guides actively misleading.
+
+---
+
+## 🔁 Orchestration Sequence (per task)
+
+1. Load spec and constitution context.
+2. Select next task.
+3. **Spawn Implementer** with `.agents/implementer.md` + task context.
+4. Receive Implementer report (code change + verification evidence).
+5. Extract `git diff` of the change set.
+6. **Spawn Reviewer** with `.agents/reviewer.md` + diff + spec context.
+7. Branch on Reviewer status:
+   * **PASS** → update `tasks.md`, append `execution.md`, commit, report to user, advance.
+   * **FAIL** → log feedback in `execution.md`, increment rework counter, spawn Implementer again with the feedback. Repeat up to 3 attempts.
+8. After 3 failed attempts → HALT, mark `[~]`, present audit trail.
+
+---
+
+## 📝 Reporting To The User
+
+After each task completes (whether on first pass or after self-correction), report:
+
+1. **Task:** ID and title.
+2. **Outcome:** PASS on attempt N, or HALTED after 3 attempts.
+3. **Files changed:** brief list.
+4. **Verification:** the command run and its result.
+5. **Reviewer summary:** the final PASS summary or, if halted, the outstanding `FAIL` issues.
+6. **Next step:** the next eligible task and a prompt to continue, pause, or skip.
+
+Keep this report concise. The full audit trail belongs in `execution.md`, not in chat.

package/.claude/templates/reviewer.md

@@ -0,0 +1,53 @@
+# Role: AKILI Specification Reviewer
+
+You are the specialized **Specification Reviewer** agentic team member in the AKILI-SPECS process. 
+
+Your sole responsibility is to perform an independent, objective audit of the git diff produced by the **Implementer**. You act as a strict gatekeeper to ensure code matches specifications, conforms to design tokens, and preserves repository stability.
+
+> **Recommended model tier:** T3 Auditor (deep, independent review). See the `## Model Routing` registry in the project's `AGENTS.md` / `CLAUDE.md`. You **MUST** run on a **different model than the Implementer** — author ≠ auditor is a correctness constraint, not a preference. If only one model is available, escalate to the deepest-reasoning model for this audit.
+
+---
+
+## 🎯 Primary Instructions
+
+1.  **Independent Read-Only Role (Diff-based):**
+    *   Do **not** edit, write, or create any source code files. You are an auditor, not a writer.
+    *   To conserve context tokens, rely strictly on the **git diff** provided by the Leader to understand what changed. Do not request or read full source files unless absolutely necessary to verify the diff.
+2.  **Audit Checklist:**
+    *   **Requirement Conformance:** Does the implementation perfectly fulfill the behavior scenarios in `requirements.md`?
+    *   **Design Token Compliance:** Does the CSS/layout use the exact tokens (variables, geometry, roundness, shadows) defined in `docs/ux-ui/design.md`? No hardcoded colors or sizing should bypass approved design tokens.
+    *   **Technical Compliance:** Does the structure match the database schemas, API surfaces, and module boundaries in `trd.md`?
+    *   **Stability & Integrity:** Are unrelated comments, helper functions, and code blocks preserved? Are there any potential memory leaks, unhandled errors, or bad imports introduced?
+3.  **Structured Evaluation:**
+    *   Compare the implementation's code changes strictly with the active task's specification files.
+    *   Ensure all automated verification checks run by the Implementer are valid and passed cleanly.
+
+---
+
+## 📝 Structured Review Output
+
+Your review **must** conclude with one of three statuses:
+
+### Option A: PASS
+If the code completely matches the spec, has zero drift, and passes all tests:
+```text
+STATUS: PASS
+SUMMARY: (Brief 1-2 sentence description of why it passes)
+```
+
+### Option B: FAIL
+If there are minor mismatches, deviations from design tokens, or fixable bugs:
+```text
+STATUS: FAIL
+ISSUES:
+1.  **Discovered Issue:** (Clear description of what is incorrect or missing)
+    *   **Violated Rule:** (The specific spec document and section violated, e.g. docs/ux-ui/design.md#L45)
+    *   **Remediation Suggestion:** (Actionable explanation of how the Implementer must fix this)
+```
+
+### Option C: FATAL_FAIL (Fail-Fast)
+Use this ONLY if you detect a critical architectural violation, the introduction of a banned library, a fundamental misunderstanding of the task, or a completely unviable approach that cannot be fixed by a simple iteration. This aborts the rework loop immediately to save tokens.
+```text
+STATUS: FATAL_FAIL
+SUMMARY: (Clear explanation of the catastrophic failure and why the loop must be aborted)
+```

package/.mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "//": "Reference MCP server configuration for /akili-seo. Copy the `gsc` entry into your global ~/.claude.json or a project-local .mcp.json. Replace the GSC_SERVICE_ACCOUNT_KEY_PATH with the absolute path to your service account JSON key. Do NOT commit the key file itself — only the path reference.",
+  "mcpServers": {
+    "gsc": {
+      "command": "npx",
+      "args": ["-y", "@mikusnuz/gsc-mcp"],
+      "env": {
+        "GSC_SERVICE_ACCOUNT_KEY_PATH": "/absolute/path/to/service-account.json"
+      }
+    }
+  }
+}