@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/bundles/nextjs-trpc/CLAUDE.md

@@ -0,0 +1,76 @@
+# Project Instructions
+
+This file provides context for Claude Code. For Cursor users, see `.cursor/rules.md` and `.cursor/rules/lattice-core.mdc`. For GitHub Copilot, see `.github/copilot-instructions.md` and `.github/instructions/lattice-core.instructions.md`. For Codex users, see `AGENTS.md` and `docs/rules/codex.md`.
+
+## Stack
+
+- **Framework**: Next.js
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS
+- **Testing**: Jest + React Testing Library
+
+## Core Rules
+
+1. **Stay in scope** - Only implement what's explicitly requested
+2. **No placeholders** - All code must be production-ready
+3. **Verify before coding** - Check current package versions and API compatibility
+4. **Minimal changes** - Keep modifications localized and simple
+5. **Test everything** - Run lint, typecheck, test, and build before submitting
+6. **Never expose secrets** - API keys, tokens, passwords, and credentials must NEVER be committed to version control
+
+## Claude Code Surfaces
+
+- `CLAUDE.md` is the shared project instruction file.
+- `.claude/rules/lattice-core.md` is path-scoped source guidance for code edits.
+- `.claude/skills/lattice-verify/SKILL.md` defines the repeatable verification workflow. Use `/lattice-verify` before final handoff or release work.
+- `.claude/settings.json` contains project permissions and hook wiring.
+- `.mcp.json` contains disabled MCP server templates. Approve and enable only the servers this project actually needs.
+
+## Verification Commands
+
+```bash
+npm run lint       # ESLint check
+npm run typecheck  # TypeScript check
+npm test           # Run tests
+npm run build      # Production build
+npm run verify     # All checks via Lattice
+```
+
+## Security Rules (CRITICAL)
+
+- **NEVER** commit API keys, secrets, tokens, or credentials to version control
+- **ALWAYS** use environment variables (`.env.local`, `.env`) for sensitive data
+- **ALWAYS** ensure `.env*` files are in `.gitignore`
+- **NEVER** hardcode secrets in source code, even in comments
+- **ONLY** access sensitive keys server-side (never expose to client-side code)
+
+## Next.js Guidelines
+
+- Use App Router (`app/` directory)
+- Server Components by default, `"use client"` only when needed
+- Follow Next.js file conventions: `layout.tsx`, `page.tsx`, `loading.tsx`, `error.tsx`
+- Use Next.js Image component for optimized images
+
+## Before Making Changes
+
+1. Restate the scope in one paragraph
+2. Identify files to create or modify
+3. Check existing patterns in the codebase
+4. Verify package versions are current
+
+## After Making Changes
+
+1. Run all verification commands
+2. Fix any failures before proceeding
+3. Report verification results
+
+## Hard Stops
+
+- If requirements conflict -> ask for clarification
+- If verification fails -> fix before continuing
+- If scope is unclear -> ask for clarification
+- If you can't verify an API or version -> ask
+- If code contains hardcoded secrets -> STOP and use environment variables
+
+---
+*Generated by Lattice Project Builder*

package/bundles/nextjs-trpc/PROJECT_GUIDE.md

@@ -0,0 +1,187 @@
+# Next.js + tRPC Starter — Project Guide
+
+This is your project guide for building a type-safe full-stack app with Next.js and tRPC.
+
+## Stack Overview
+
+| Layer | Technology | Purpose |
+|-------|------------|---------|
+| Frontend | Next.js + React | App Router, Server Components |
+| API | tRPC | End-to-end type safety |
+| Database | Prisma + PostgreSQL | Type-safe ORM |
+| Validation | Zod | Runtime validation |
+| Analytics | PostHog | Product analytics |
+| Monitoring | Sentry | Error tracking |
+
+**IMPORTANT FOR AI:** Always check `package.json` for the exact versions of dependencies before referencing them in code or documentation. Never hardcode version numbers—they change frequently.
+
+## Project Structure
+
+```
+├── app/
+│   ├── api/trpc/[trpc]/route.ts
+│   ├── _trpc/
+│   │   ├── client.ts
+│   │   └── server.ts
+│   ├── layout.tsx
+│   └── page.tsx
+├── server/
+│   ├── routers/
+│   │   ├── _app.ts
+│   │   ├── user.ts
+│   │   └── post.ts
+│   ├── trpc.ts
+│   └── context.ts
+├── prisma/
+│   └── schema.prisma
+├── components/
+└── lib/
+```
+
+---
+
+## Phase 1: Foundation (Days 1-2)
+
+### Goal
+Set up tRPC with Prisma, a public health check, and a fail-closed User CRUD skeleton.
+
+### Tasks
+
+1. **Configure Prisma**
+   - Define schema in `prisma/schema.prisma`
+   - Run `npx prisma db push`
+   - Generate client: `npx prisma generate`
+
+2. **Set up tRPC server**
+   - Create context with Prisma client
+   - Define base router
+   - Create API route handler
+
+3. **Set up tRPC client**
+   - Create React Query provider
+   - Configure tRPC hooks
+
+4. **Create first router**
+   - Keep User CRUD resolvers behind `userDataRequiresAuthAndAuthorizationProcedure`
+   - Do not resolve Prisma from User procedures until Phase 2 authentication and record-level authorization are complete
+   - Input validation with Zod
+
+### Acceptance Criteria
+
+- [ ] Prisma connected to database
+- [ ] Public health procedure callable from client
+- [ ] User list/create procedures return `UNAUTHORIZED` before Prisma is resolved
+- [ ] Full type safety across stack
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 2: Authentication (Days 3-4)
+
+### Goal
+Add auth with protected procedures.
+
+### Tasks
+
+1. **Add auth context**
+   - Verify the provider session on the server and place its identity in tRPC context
+   - Protected procedure middleware
+
+2. **Create auth router**
+   - Login/logout procedures
+   - Session management
+
+3. **Protect routes**
+   - Middleware for auth check
+   - Type-safe verified user in context
+   - Define record ownership and scope every User read and write to the verified identity
+   - Select only the fields each caller is authorized to receive
+
+### Acceptance Criteria
+
+- [ ] Users can log in
+- [ ] Protected procedures reject unauthenticated
+- [ ] Authenticated callers cannot read or change another user's records
+- [ ] User list responses omit email and internal fields unless the product explicitly requires and authorizes them
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 3: Core Features (Days 5-10)
+
+### Goal
+Build your main application features.
+
+### Tasks
+
+1. **Define routers for each domain**
+2. **Implement procedures with validation**
+3. **Add optimistic updates**
+4. **Handle errors gracefully**
+
+### Acceptance Criteria
+
+- [ ] Core CRUD works
+- [ ] Types flow end-to-end
+- [ ] `npm run verify` passes
+
+---
+
+## Phase 4: Polish & Launch (Days 11-14)
+
+### Goal
+Production-ready application.
+
+### Tasks
+
+1. **Add Sentry error tracking**
+2. **Add PostHog analytics**
+3. **Optimize queries**
+4. **Deploy to Vercel**
+
+### Acceptance Criteria
+
+- [ ] Errors tracked in Sentry
+- [ ] Analytics working
+- [ ] `npm run release-check` passes
+
+---
+
+## Key tRPC Patterns
+
+### Fail-closed User procedure (Phase 1)
+```typescript
+export const userRouter = router({
+  create: userDataRequiresAuthAndAuthorizationProcedure
+    .input(z.object({ name: z.string(), email: z.email() }))
+    .mutation(async ({ input }) => {
+      return getPrisma().user.create({ data: input });
+    }),
+});
+```
+
+The resolver is intentionally unreachable until Phase 2. Keeping the CRUD shape here does not make it safe to
+enable. Replace the fail-closed procedure only after the session and ownership checks below are implemented and
+tested.
+
+### Protected and ownership-scoped procedure (Phase 2)
+```typescript
+const protectedProcedure = publicProcedure.use(({ ctx, next }) => {
+  if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' });
+  return next({ ctx: { ...ctx, user: ctx.session.user } });
+});
+
+const myProfile = protectedProcedure.query(({ ctx }) =>
+  ctx.prisma.user.findUnique({
+    where: { id: ctx.user.id },
+    select: { id: true, name: true },
+  }),
+);
+```
+
+Authentication establishes identity. Authorization still requires every procedure to enforce ownership or an
+explicit role. Never replace the fail-closed procedure with a broad authenticated `findMany()`.
+
+---
+
+*Generated by Lattice — AI workers are fast. Lattice keeps them building right.*

package/bundles/nextjs-trpc/README.md

@@ -0,0 +1,49 @@
+# Next.js + tRPC Starter
+
+Built with [Lattice Project Builder](https://latticeai.app).
+
+## Getting Started
+
+1. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+2. Review `.env.example` and fill in the variables your selected services need.
+
+3. Run the development server:
+   ```bash
+   npm run dev
+   ```
+
+4. Open [http://localhost:3000](http://localhost:3000)
+
+## Included Scaffold
+
+- PROJECT_GUIDE.md with the planned build scope
+- AI guardrails for Cursor, Codex, and Claude Code
+- GitHub Actions CI and shared verification commands
+- Prisma 7 schema, config, PostgreSQL adapter, and client
+- tRPC API route and TanStack Query application shell
+- Public health procedure plus a fail-closed User CRUD skeleton
+- Sentry runtime initialization and error boundary
+
+## User data is disabled by default
+
+The starter does not expose User records or accept User writes before authentication is implemented. Both
+`users.list` and `users.create` return `UNAUTHORIZED` before Prisma is resolved. During Phase 2, connect a
+server-verified session to the tRPC context, define who owns each User record, and scope every read and write to
+that verified identity before replacing the fail-closed procedure. Do not enable an authenticated but unscoped
+User list.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | Start development server |
+| `npm run build` | Build for production |
+| `npm run start` | Start production server |
+| `npm run lint` | Run ESLint |
+| `npm run typecheck` | Run TypeScript checks |
+| `npm run test` | Run tests |
+| `npm run verify` | Run all checks |

package/bundles/nextjs-trpc/app/api/trpc/[trpc]/route.ts

@@ -0,0 +1,12 @@
+import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
+import { appRouter } from "@/server/routers/_app";
+
+const handler = (request: Request) =>
+  fetchRequestHandler({
+    endpoint: "/api/trpc",
+    req: request,
+    router: appRouter,
+    createContext: () => ({}),
+  });
+
+export { handler as GET, handler as POST };

package/bundles/nextjs-trpc/app/global-error.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import * as Sentry from "@sentry/nextjs";
+import NextError from "next/error";
+import { useEffect } from "react";
+
+export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+  useEffect(() => {
+    Sentry.captureException(error);
+  }, [error]);
+
+  return (
+    <html>
+      <body><NextError statusCode={0} /></body>
+    </html>
+  );
+}

package/bundles/nextjs-trpc/app/globals.css

@@ -0,0 +1,55 @@
+@import "tailwindcss";
+
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 84% 4.9%;
+  --popover: 0 0% 100%;
+  --popover-foreground: 222.2 84% 4.9%;
+  --primary: 221.2 83.2% 53.3%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --secondary-foreground: 222.2 47.4% 11.2%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --accent: 210 40% 96.1%;
+  --accent-foreground: 222.2 47.4% 11.2%;
+  --destructive: 0 84.2% 60.2%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 221.2 83.2% 53.3%;
+  --radius: 0.5rem;
+}
+
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+  --card: 222.2 84% 4.9%;
+  --card-foreground: 210 40% 98%;
+  --popover: 222.2 84% 4.9%;
+  --popover-foreground: 210 40% 98%;
+  --primary: 217.2 91.2% 59.8%;
+  --primary-foreground: 222.2 47.4% 11.2%;
+  --secondary: 217.2 32.6% 17.5%;
+  --secondary-foreground: 210 40% 98%;
+  --muted: 217.2 32.6% 17.5%;
+  --muted-foreground: 215 20.2% 65.1%;
+  --accent: 217.2 32.6% 17.5%;
+  --accent-foreground: 210 40% 98%;
+  --destructive: 0 62.8% 30.6%;
+  --destructive-foreground: 210 40% 98%;
+  --border: 217.2 32.6% 17.5%;
+  --input: 217.2 32.6% 17.5%;
+  --ring: 224.3 76.3% 48%;
+}
+
+* {
+  border-color: hsl(var(--border));
+}
+
+body {
+  background-color: hsl(var(--background));
+  color: hsl(var(--foreground));
+}

package/bundles/nextjs-trpc/app/layout.tsx

@@ -0,0 +1,19 @@
+import type { Metadata } from "next";
+import { Inter } from "next/font/google";
+import { Providers } from "@/app/providers";
+import "./globals.css";
+
+const inter = Inter({ subsets: ["latin"] });
+
+export const metadata: Metadata = {
+  title: "Next.js + tRPC Starter",
+  description: "Built with Lattice Project Builder",
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body className={inter.className}><Providers>{children}</Providers></body>
+    </html>
+  );
+}

package/bundles/nextjs-trpc/app/page.tsx

@@ -0,0 +1,16 @@
+import { UserAccessSetup } from "@/components/user-list";
+
+export default function HomePage() {
+  return (
+    <main className="min-h-screen bg-gray-50 px-6 py-16 text-gray-900">
+      <div className="mx-auto max-w-4xl space-y-8">
+        <header className="space-y-3">
+          <p className="text-sm font-semibold text-blue-700">tRPC + Prisma</p>
+          <h1 className="text-4xl font-bold">Next.js + tRPC Starter</h1>
+          <p className="text-gray-600">This starter includes a public tRPC health check and a fail-closed User CRUD skeleton.</p>
+        </header>
+        <UserAccessSetup />
+      </div>
+    </main>
+  );
+}

package/bundles/nextjs-trpc/app/providers.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createTRPCClient, httpBatchLink } from "@trpc/client";
+import { useState } from "react";
+import type { AppRouter } from "@/server/routers/_app";
+import { TRPCProvider } from "@/lib/trpc/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(
+    () => new QueryClient({ defaultOptions: { queries: { staleTime: 60_000 } } }),
+  );
+  const [trpcClient] = useState(() =>
+    createTRPCClient<AppRouter>({ links: [httpBatchLink({ url: "/api/trpc" })] }),
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <TRPCProvider trpcClient={trpcClient} queryClient={queryClient}>
+        {children}
+      </TRPCProvider>
+    </QueryClientProvider>
+  );
+}

package/bundles/nextjs-trpc/components/ui/button.tsx

@@ -0,0 +1,39 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
+  size?: "default" | "sm" | "lg" | "icon";
+}
+
+const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant = "default", size = "default", ...props }, ref) => {
+    return (
+      <button
+        className={cn(
+          "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50",
+          {
+            "bg-primary text-primary-foreground hover:bg-primary/90": variant === "default",
+            "bg-destructive text-destructive-foreground hover:bg-destructive/90": variant === "destructive",
+            "border border-input bg-background hover:bg-accent hover:text-accent-foreground": variant === "outline",
+            "bg-secondary text-secondary-foreground hover:bg-secondary/80": variant === "secondary",
+            "hover:bg-accent hover:text-accent-foreground": variant === "ghost",
+            "text-primary underline-offset-4 hover:underline": variant === "link",
+          },
+          {
+            "h-10 px-4 py-2": size === "default",
+            "h-9 rounded-md px-3": size === "sm",
+            "h-11 rounded-md px-8": size === "lg",
+            "h-10 w-10": size === "icon",
+          },
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Button.displayName = "Button";
+
+export { Button };

package/bundles/nextjs-trpc/components/ui/card.tsx

@@ -0,0 +1,53 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+const Card = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(
+        "rounded-lg border bg-card text-card-foreground shadow-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+);
+Card.displayName = "Card";
+
+const CardHeader = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn("flex flex-col space-y-1.5 p-6", className)} {...props} />
+  )
+);
+CardHeader.displayName = "CardHeader";
+
+const CardTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => (
+    <h3 ref={ref} className={cn("text-2xl font-semibold leading-none tracking-tight", className)} {...props} />
+  )
+);
+CardTitle.displayName = "CardTitle";
+
+const CardDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => (
+    <p ref={ref} className={cn("text-sm text-muted-foreground", className)} {...props} />
+  )
+);
+CardDescription.displayName = "CardDescription";
+
+const CardContent = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
+  )
+);
+CardContent.displayName = "CardContent";
+
+const CardFooter = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => (
+    <div ref={ref} className={cn("flex items-center p-6 pt-0", className)} {...props} />
+  )
+);
+CardFooter.displayName = "CardFooter";
+
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/bundles/nextjs-trpc/components/ui/index.ts

@@ -0,0 +1,4 @@
+export { Button } from "./button";
+export { Input } from "./input";
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent } from "./card";
+export { Spinner } from "./spinner";

package/bundles/nextjs-trpc/components/ui/input.tsx

@@ -0,0 +1,23 @@
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+export type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
+
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type, ...props }, ref) => {
+    return (
+      <input
+        type={type}
+        className={cn(
+          "flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+Input.displayName = "Input";
+
+export { Input };

package/bundles/nextjs-trpc/components/ui/spinner.tsx

@@ -0,0 +1,22 @@
+import { cn } from "@/lib/utils";
+
+interface SpinnerProps {
+  className?: string;
+  size?: "sm" | "default" | "lg";
+}
+
+export function Spinner({ className, size = "default" }: SpinnerProps) {
+  return (
+    <div
+      className={cn(
+        "animate-spin rounded-full border-2 border-current border-t-transparent",
+        {
+          "h-4 w-4": size === "sm",
+          "h-6 w-6": size === "default",
+          "h-8 w-8": size === "lg",
+        },
+        className
+      )}
+    />
+  );
+}

package/bundles/nextjs-trpc/components/user-list.tsx

@@ -0,0 +1,17 @@
+export function UserAccessSetup() {
+  return (
+    <section className="space-y-4 rounded-lg border border-amber-200 bg-amber-50 p-6">
+      <h2 className="text-xl font-semibold text-amber-950">Connect authentication before enabling user data</h2>
+      <p className="text-amber-900">
+        The starter keeps its User procedures disabled by default. The public health procedure is ready to use,
+        while User reads and writes return an unauthorized error without opening a database connection.
+      </p>
+      <ol className="list-decimal space-y-2 pl-5 text-sm text-amber-900">
+        <li>Add your authentication provider and verify its session on the server.</li>
+        <li>Place the verified user identity in the tRPC context.</li>
+        <li>Define record ownership and scope every User query and mutation to that identity.</li>
+        <li>Replace the fail-closed User procedure only after authentication and authorization tests pass.</li>
+      </ol>
+    </section>
+  );
+}

package/bundles/nextjs-trpc/docs/LATTICE_RELEASE_WORKFLOW.md

@@ -0,0 +1,53 @@
+# Lattice Release Workflow
+
+This repository uses a portable feature-to-release contract. It coordinates work across Codex, Claude Code, GitHub Copilot, Cursor, and other tools without assuming that every provider has direct peer messaging.
+
+## Source of Truth
+
+- Policy: `.lattice/release-workflow.json`
+- Handoff schema: `.lattice/schemas/feature-handoff.schema.json`
+- Handoff template: `.lattice/templates/feature-handoff.json`
+- Feature procedure: `.agents/skills/lattice-feature-handoff/SKILL.md`
+- Release review procedure: `.agents/skills/lattice-release-manager/SKILL.md`
+- Mutable local state: `.lattice/runtime/` (Git-ignored)
+
+Stable instructions define roles and contracts. Live task IDs, production SHAs, deployment IDs, and provider state belong in current handoffs or ignored runtime state.
+
+## Workflow
+
+1. **Feature work** — A feature agent starts from an approved base in an isolated worktree, implements only the assigned scope, and runs proportionate checks.
+2. **Handoff** — The feature agent records exact base/head SHAs, diff scope, verification, operational impacts, risks, and approvals in the JSON handoff.
+3. **Release audit** — The Release Manager independently resolves the repository and reviews the exact candidate. The manager accepts for owner approval, requests rework, or blocks.
+4. **Candidate preparation** — A release candidate may be prepared only after its constituent handoffs pass review.
+5. **Owner approval** — Production promotion, migrations, provider/account writes, secret or environment changes, and destructive actions require explicit owner approval.
+6. **Deployment and live proof** — Deployment and live verification are separate states. A successful build or preview is not a production release.
+7. **Cleanup** — Feature worktrees and branches are cleaned only after the authorized candidate is proven live and rollback evidence is current.
+
+## Transport
+
+Use the narrowest available transport:
+
+1. A native task message when the environment exposes the capability and the exact destination is bound.
+2. The shared GitHub issue, pull request, or comment.
+3. The versioned handoff artifact, with its exact path surfaced to the owner.
+
+Never claim that a handoff was delivered unless the transport returned evidence. The message is notification; the handoff is the durable evidence.
+
+## Status Meanings
+
+- `READY_FOR_RELEASE`: ready for independent Release Manager review.
+- `NEEDS_REWORK`: a confirmed defect, failed gate, incomplete proof, or scope mismatch remains.
+- `BLOCKED`: lineage, authority, environment, or another prerequisite prevents safe progress.
+
+None of these statuses means merged, deployed, released, or live.
+
+## Provider Adapters
+
+- **Codex:** project custom agents in `.codex/agents/` plus the shared skills.
+- **Claude Code:** project subagents in `.claude/agents/`; the feature role requests worktree isolation.
+- **GitHub Copilot:** custom agents in `.github/agents/`; issues, pull requests, and comments are the portable control plane.
+- **Cursor:** shared `AGENTS.md`, `.cursor/rules.md`, and `.agents/skills/`. Native peer messaging is not required by this contract.
+
+## Secret and Data Boundary
+
+Do not put credentials, tokens, private keys, payment data, direct personal contact data, or secret values in a handoff. Name an environment variable or provider surface when needed; do not copy its value.