@therocketcode/gsd-core 1.4.0

package/gsd-core/references/ai-frameworks.md

@@ -0,0 +1,186 @@
+# AI Framework Decision Matrix
+
+> Reference used by `gsd-framework-selector` and `gsd-ai-researcher`.
+> Distilled from official docs, benchmarks, and developer reports (2026).
+
+---
+
+## Quick Picks
+
+| Situation | Pick |
+|-----------|------|
+| Simplest path to a working agent (OpenAI) | OpenAI Agents SDK |
+| Simplest path to a working agent (model-agnostic) | CrewAI |
+| Production RAG / document Q&A | LlamaIndex |
+| Complex stateful workflows with branching | LangGraph |
+| Multi-agent teams with defined roles | CrewAI |
+| Code-aware autonomous agents (Anthropic) | Claude Agent SDK |
+| "I don't know my requirements yet" | LangChain |
+| Regulated / audit-trail required | LangGraph |
+| Enterprise Microsoft/.NET shops | AutoGen/AG2 |
+| Google Cloud / Gemini-committed teams | Google ADK |
+| Pure NLP pipelines with explicit control | Haystack |
+
+---
+
+## Framework Profiles
+
+### CrewAI
+- **Type:** Multi-agent orchestration
+- **Language:** Python only
+- **Model support:** Model-agnostic
+- **Learning curve:** Beginner (role/task/crew maps to real teams)
+- **Best for:** Content pipelines, research automation, business process workflows, rapid prototyping
+- **Avoid if:** Fine-grained state management, TypeScript, fault-tolerant checkpointing, complex conditional branching
+- **Strengths:** Fastest multi-agent prototyping, 5.76x faster than LangGraph on QA tasks, built-in memory (short/long/entity/contextual), Flows architecture, standalone (no LangChain dep)
+- **Weaknesses:** Limited checkpointing, coarse error handling, Python only
+- **Eval concerns:** Task decomposition accuracy, inter-agent handoff, goal completion rate, loop detection
+
+### LlamaIndex
+- **Type:** RAG and data ingestion
+- **Language:** Python + TypeScript
+- **Model support:** Model-agnostic
+- **Learning curve:** Intermediate
+- **Best for:** Legal research, internal knowledge assistants, enterprise document search, any system where retrieval quality is the #1 priority
+- **Avoid if:** Primary need is agent orchestration, multi-agent collaboration, or chatbot conversation flow
+- **Strengths:** Best-in-class document parsing (LlamaParse), 35% retrieval accuracy improvement, 20-30% faster queries, mixed retrieval strategies (vector + graph + reranker)
+- **Weaknesses:** Data framework first — agent orchestration is secondary
+- **Eval concerns:** Context faithfulness, hallucination, answer relevance, retrieval precision/recall
+
+### LangChain
+- **Type:** General-purpose LLM framework
+- **Language:** Python + TypeScript
+- **Model support:** Model-agnostic (widest ecosystem)
+- **Learning curve:** Intermediate–Advanced
+- **Best for:** Evolving requirements, many third-party integrations, teams wanting one framework for everything, RAG + agents + chains
+- **Avoid if:** Simple well-defined use case, RAG-primary (use LlamaIndex), complex stateful workflows (use LangGraph), performance at scale is critical
+- **Strengths:** Largest community and integration ecosystem, 25% faster development vs scratch, covers RAG/agents/chains/memory
+- **Weaknesses:** Abstraction overhead, p99 latency degrades under load, complexity creep risk
+- **Eval concerns:** End-to-end task completion, chain correctness, retrieval quality
+
+### LangGraph
+- **Type:** Stateful agent workflows (graph-based)
+- **Language:** Python + TypeScript (full parity)
+- **Model support:** Model-agnostic (inherits LangChain integrations)
+- **Learning curve:** Intermediate–Advanced (graph mental model)
+- **Best for:** Production-grade stateful workflows, regulated industries, audit trails, human-in-the-loop flows, fault-tolerant multi-step agents
+- **Avoid if:** Simple chatbot, purely linear workflow, rapid prototyping
+- **Strengths:** Best checkpointing (every node), time-travel debugging, native Postgres/Redis persistence, streaming support, chosen by 62% of developers for stateful agent work (2026)
+- **Weaknesses:** More upfront scaffolding, steeper curve, overkill for simple cases
+- **Eval concerns:** State transition correctness, goal completion rate, tool use accuracy, safety guardrails
+
+### OpenAI Agents SDK
+- **Type:** Native OpenAI agent framework
+- **Language:** Python + TypeScript
+- **Model support:** Optimized for OpenAI (supports 100+ via Chat Completions compatibility)
+- **Learning curve:** Beginner (4 primitives: Agents, Handoffs, Guardrails, Tracing)
+- **Best for:** OpenAI-committed teams, rapid agent prototyping, voice agents (gpt-realtime), teams wanting visual builder (AgentKit)
+- **Avoid if:** Model flexibility needed, complex multi-agent collaboration, persistent state management required, vendor lock-in concern
+- **Strengths:** Simplest mental model, built-in tracing and guardrails, Handoffs for agent delegation, Realtime Agents for voice
+- **Weaknesses:** OpenAI vendor lock-in, no built-in persistent state, younger ecosystem
+- **Eval concerns:** Instruction following, safety guardrails, escalation accuracy, tone consistency
+
+### Claude Agent SDK (Anthropic)
+- **Type:** Code-aware autonomous agent framework
+- **Language:** Python + TypeScript
+- **Model support:** Claude models only
+- **Learning curve:** Intermediate (18 hook events, MCP, tool decorators)
+- **Best for:** Developer tooling, code generation/review agents, autonomous coding assistants, MCP-heavy architectures, safety-critical applications
+- **Avoid if:** Model flexibility needed, stable/mature API required, use case unrelated to code/tool-use
+- **Strengths:** Deepest MCP integration, built-in filesystem/shell access, 18 lifecycle hooks, automatic context compaction, extended thinking, safety-first design
+- **Weaknesses:** Claude-only vendor lock-in, newer/evolving API, smaller community
+- **Eval concerns:** Tool use correctness, safety, code quality, instruction following
+
+### AutoGen / AG2 / Microsoft Agent Framework
+- **Type:** Multi-agent conversational framework
+- **Language:** Python (AG2), Python + .NET (Microsoft Agent Framework)
+- **Model support:** Model-agnostic
+- **Learning curve:** Intermediate–Advanced
+- **Best for:** Research applications, conversational problem-solving, code generation + execution loops, Microsoft/.NET shops
+- **Avoid if:** You want ecosystem stability, deterministic workflows, or "safest long-term bet" (fragmentation risk)
+- **Strengths:** Most sophisticated conversational agent patterns, code generation + execution loop, async event-driven (v0.4+), cross-language interop (Microsoft Agent Framework)
+- **Weaknesses:** Ecosystem fragmented (AutoGen maintenance mode, AG2 fork, Microsoft Agent Framework preview) — genuine long-term risk
+- **Eval concerns:** Conversation goal completion, consensus quality, code execution correctness
+
+### Google ADK (Agent Development Kit)
+- **Type:** Multi-agent orchestration framework
+- **Language:** Python + Java
+- **Model support:** Optimized for Gemini; supports other models via LiteLLM
+- **Learning curve:** Intermediate (agent/tool/session model, familiar if you know LangGraph)
+- **Best for:** Google Cloud / Vertex AI shops, multi-agent workflows needing built-in session management and memory, teams already committed to Gemini, agent pipelines that need Google Search / BigQuery tool integration
+- **Avoid if:** Model flexibility is required beyond Gemini, no Google Cloud dependency acceptable, TypeScript-only stack
+- **Strengths:** First-party Google support, built-in session/memory/artifact management, tight Vertex AI and Google Search integration, own eval framework (RAGAS-compatible), multi-agent by design (sequential, parallel, loop patterns), Java SDK for enterprise teams
+- **Weaknesses:** Gemini vendor lock-in in practice, younger community than LangChain/LlamaIndex, less third-party integration depth
+- **Eval concerns:** Multi-agent task decomposition, tool use correctness, session state consistency, goal completion rate
+
+### Haystack
+- **Type:** NLP pipeline framework
+- **Language:** Python
+- **Model support:** Model-agnostic
+- **Learning curve:** Intermediate
+- **Best for:** Explicit, auditable NLP pipelines, document processing with fine-grained control, enterprise search, regulated industries needing transparency
+- **Avoid if:** Rapid prototyping, multi-agent workflows, or you want a large community
+- **Strengths:** Explicit pipeline control, strong for structured data pipelines, good documentation
+- **Weaknesses:** Smaller community, less agent-oriented than alternatives
+- **Eval concerns:** Extraction accuracy, pipeline output validity, retrieval quality
+
+---
+
+## Decision Dimensions
+
+### By System Type
+
+| System Type | Primary Framework(s) | Key Eval Concerns |
+|-------------|---------------------|-------------------|
+| RAG / Knowledge Q&A | LlamaIndex, LangChain | Context faithfulness, hallucination, retrieval precision/recall |
+| Multi-agent orchestration | CrewAI, LangGraph, Google ADK | Task decomposition, handoff quality, goal completion |
+| Conversational assistants | OpenAI Agents SDK, Claude Agent SDK | Tone, safety, instruction following, escalation |
+| Structured data extraction | LangChain, LlamaIndex | Schema compliance, extraction accuracy |
+| Autonomous task agents | LangGraph, OpenAI Agents SDK | Safety guardrails, tool correctness, cost adherence |
+| Content generation | Claude Agent SDK, OpenAI Agents SDK | Brand voice, factual accuracy, tone |
+| Code automation | Claude Agent SDK | Code correctness, safety, test pass rate |
+
+### By Team Size and Stage
+
+| Context | Recommendation |
+|---------|----------------|
+| Solo dev, prototyping | OpenAI Agents SDK or CrewAI (fastest to running) |
+| Solo dev, RAG | LlamaIndex (batteries included) |
+| Team, production, stateful | LangGraph (best fault tolerance) |
+| Team, evolving requirements | LangChain (broadest escape hatches) |
+| Team, multi-agent | CrewAI (simplest role abstraction) |
+| Enterprise, .NET | AutoGen AG2 / Microsoft Agent Framework |
+
+### By Model Commitment
+
+| Preference | Framework |
+|-----------|-----------|
+| OpenAI-only | OpenAI Agents SDK |
+| Anthropic/Claude-only | Claude Agent SDK |
+| Google/Gemini-committed | Google ADK |
+| Model-agnostic (full flexibility) | LangChain, LlamaIndex, CrewAI, LangGraph, Haystack |
+
+---
+
+## Anti-Patterns
+
+1. **Using LangChain for simple chatbots** — Direct SDK call is less code, faster, and easier to debug
+2. **Using CrewAI for complex stateful workflows** — Checkpointing gaps will bite you in production
+3. **Using OpenAI Agents SDK with non-OpenAI models** — Loses the integration benefits you chose it for
+4. **Using LlamaIndex as a multi-agent framework** — It can do agents, but that's not its strength
+5. **Defaulting to LangChain without evaluating alternatives** — "Everyone uses it" ≠ right for your use case
+6. **Starting a new project on AutoGen (not AG2)** — AutoGen is in maintenance mode; use AG2 or wait for Microsoft Agent Framework GA
+7. **Choosing LangGraph for simple linear flows** — The graph overhead is not worth it; use LangChain chains instead
+8. **Ignoring vendor lock-in** — Provider-native SDKs (OpenAI, Claude) trade flexibility for integration depth; decide consciously
+
+---
+
+## Combination Plays (Multi-Framework Stacks)
+
+| Production Pattern | Stack |
+|-------------------|-------|
+| RAG with observability | LlamaIndex + LangSmith or Langfuse |
+| Stateful agent with RAG | LangGraph + LlamaIndex |
+| Multi-agent with tracing | CrewAI + Langfuse |
+| OpenAI agents with evals | OpenAI Agents SDK + Promptfoo or Braintrust |
+| Claude agents with MCP | Claude Agent SDK + LangSmith or Arize Phoenix |

package/gsd-core/references/architecture-decision.md

@@ -0,0 +1,74 @@
+# Architecture Decision — Two-Axis, Complexity-Matched
+
+Reference for `/gsd:recommend-architecture`. Recommends an architecture that **matches complexity** — explicitly avoiding both over- and under-engineering. Consumes `DOMAIN-MODEL.md` (subdomain complexity). Recommends; the user decides.
+
+## Core principle: two INDEPENDENT axes
+
+Keep these separate — conflating them is the #1 architecture error.
+
+- **Axis A — domain-logic organization:** Transaction Script → Domain Model → (Hexagonal/Clean wrapper) → CQRS → Event Sourcing. Driven by **domain complexity** (decide *per subdomain*, using DOMAIN-MODEL).
+- **Axis B — deployment topology:** Modular Monolith → Microservices. Driven by **team structure + NFRs + ops maturity** — *not* by complexity.
+
+The common sweet spot is a **Domain Model inside a modular monolith**. High scale does not imply a Domain Model; rich domain logic does not imply microservices.
+
+## Axis A — domain logic (decide per subdomain)
+
+Use the core subdomain's complexity from DOMAIN-MODEL. Apply per subdomain: the complex core may warrant a Domain Model (± Hexagonal); supporting/generic subdomains stay Transaction Script.
+
+| Rung | Move up when | Over-engineering tell |
+|------|--------------|-----------------------|
+| **Transaction Script / simple layered CRUD** (floor) | "validate → persist → return"; few rules; supporting/generic subdomains | — |
+| **Domain Model** | business rules multiply and tangle; the same invariant is duplicated across scripts; rich conditional behavior; long-lived core | rich aggregates wrapping what is really CRUD; anemic getter-bag "domain" objects |
+| **Hexagonal / Clean wrapper** (orthogonal — wraps either above) | real domain logic worth isolating; multiple/swappable adapters (DB, queue, 3rd-party APIs); high testability need; long lifespan | ports/interfaces with exactly one forever-implementation; DTO-mapping boilerplate around a CRUD endpoint |
+| **CQRS** | read and write models genuinely diverge; reads ≫ writes; write model under strain | separate read/write stacks where one model serves both fine |
+| **Event Sourcing** | audit/temporal history is a hard requirement (finance, compliance, "reconstruct past state") | ES on a simple entity with no audit/temporal need |
+
+## Axis B — deployment topology
+
+- **Modular Monolith — the DEFAULT for greenfield.** One team; domain still being learned; few moving parts; fast to change. This is the recommended floor. Enforce internal module boundaries (separate schemas, dependency rules).
+- **Microservices — only when ALL "you must be this tall" gates pass:**
+  1. **Multiple independent teams** needing independent deploy cadence (Conway / Team Topologies).
+  2. **CD / monitoring / DevOps maturity** already in place.
+  3. **Bounded contexts well-understood** already (not still being discovered).
+  If **any** is "no" → recommend **modular monolith and stop**, regardless of complexity. (The "microservice premium": below a complexity+org threshold the distributed tax is pure loss.)
+- **Component-level split (Hard Parts):** for a specific component, score the **6 disintegrators** (low cohesion · divergent volatility · divergent scalability · fault isolation · differential security · independent extensibility) against the **4 integrators** (ACID across the data · tightly-coupled workflow · heavy shared code · tight data relationships). Net disintegrators ≫ integrators → candidate extraction; otherwise keep it in the monolith.
+- **Distributed monolith** (services that can't deploy independently) is the failure mode — you pay the premium and get none of the autonomy. Avoid.
+
+## Non-functional drivers (quick matrix)
+
+| Driver | Low → | High → pushes toward |
+|---|---|---|
+| Domain complexity | Transaction Script | Domain Model (+ Hexagonal) |
+| Read/write asymmetry | single model | CQRS |
+| Audit / temporal requirement | normal persistence | Event Sourcing |
+| Scale (uniform) | monolith + replicas | still monolith — scale ≠ microservices |
+| Scale (divergent per component) | modular monolith | extract that component (disintegrator) |
+| Availability / fault isolation | monolith | isolate failure-prone component |
+| Differential security | one trust boundary | separate the stricter-security component |
+| Integration count (adapters) | direct calls | Hexagonal ports & adapters |
+| Expected lifespan | short → keep simple (sacrificial) | long → Domain Model + Hexagonal + fitness functions |
+| Team count / ops maturity | 1 team / low → monolith | many independent teams / high → microservices viable |
+
+## Over- AND under-engineering
+
+**Over-engineering tells:** one-implementation ports; rich aggregates over structural CRUD; CQRS/ES with no asymmetry or audit need; "microservice envy"; distributed monolith; elaborate config/abstraction "wanting all options all the time."
+
+**Under-engineering tells:** the same invariant duplicated across many transaction scripts; a big-ball-of-mud monolith with no enforced module boundaries; a complex/regulated domain modeled as thin CRUD; no audit trail where compliance needs it; no ADRs / no fitness functions.
+
+**The meta-tell (use this to settle every rung):** if you cannot point to a **current, concrete** requirement — a real second adapter, a real divergent-scaling component, a real second team, a real audit mandate — that justifies a rung, you are **over-engineering**. If such a requirement exists and you ignored it, you are **under-engineering**.
+
+## Default baseline (when in doubt)
+
+**Modular monolith + Domain Model only in the complex core bounded contexts + Transaction Script in the simple/CRUD ones + ADRs + boundary fitness functions.** This is the modern consensus starting point.
+
+## Always
+
+- Record the decision as an **ADR** — capture the *why*, the trade-offs, and the alternatives rejected (*why* matters more than *how*).
+- Recommend **fitness functions** to enforce the chosen boundaries (e.g., "no cross-module DB access," module dependency rules) so a modular monolith doesn't rot.
+- Frame as a **sacrificial architecture** where appropriate (a monolith you may later split is fine if it gets you to market and teaches the boundaries).
+- **Recommend, don't dictate.** Present the trade-offs and your recommended option with rationale; the user has context you lack — let them choose.
+
+## Consumes / produces
+
+- **Consumes** `DOMAIN-MODEL.md` (core/supporting/generic + complexity) → Axis A per subdomain. If absent, ask the complexity questions directly (and suggest running `/gsd:model-domain` first).
+- **Produces** `.planning/adr/NNNN-architecture.md` (the decision) + an architectural-decisions table. Feeds `testing-strategy` (test shape follows architecture) and `plan-phase`.

package/gsd-core/references/artifact-types.md

@@ -0,0 +1,131 @@
+# GSD Artifact Types
+
+This reference documents all artifact types in the GSD planning taxonomy. Each type has a defined
+shape, lifecycle, location, and consumption mechanism. A well-formatted artifact that no workflow
+reads is inert — the consumption mechanism is what gives an artifact meaning.
+
+---
+
+## Core Artifacts
+
+### ROADMAP.md
+- **Shape**: Milestone + phase listing with goals and canonical refs
+- **Lifecycle**: Created → Updated per milestone → Archived
+- **Location**: `.planning/ROADMAP.md`
+- **Consumed by**: `plan-phase`, `discuss-phase`, `execute-phase`, `progress`, `state` commands
+
+### STATE.md
+- **Shape**: Current position tracker (phase, plan, progress, decisions)
+- **Lifecycle**: Continuously updated throughout the project
+- **Location**: `.planning/STATE.md`
+- **Consumed by**: All orchestration workflows; `resume-project`, `progress`, `next` commands
+
+### REQUIREMENTS.md
+- **Shape**: Numbered acceptance criteria with traceability table
+- **Lifecycle**: Created at project start → Updated as requirements are satisfied
+- **Location**: `.planning/REQUIREMENTS.md`
+- **Consumed by**: `discuss-phase`, `plan-phase`, CONTEXT.md generation; executor marks complete
+
+### CONTEXT.md (per-phase)
+- **Shape**: 6-section format: domain, decisions, canonical_refs, code_context, specifics, deferred
+- **Lifecycle**: Created before planning → Used during planning and execution → Superseded by next phase
+- **Location**: `.planning/phases/XX-name/XX-CONTEXT.md`
+- **Consumed by**: `plan-phase` (reads decisions), `execute-phase` (reads code_context and canonical_refs)
+
+### PLAN.md (per-plan)
+- **Shape**: Frontmatter + objective + tasks with types + success criteria + output spec
+- **Lifecycle**: Created by planner → Executed → SUMMARY.md produced
+- **Location**: `.planning/phases/XX-name/XX-YY-PLAN.md`
+- **Consumed by**: `execute-phase` executor; task commits reference plan IDs
+
+### SUMMARY.md (per-plan)
+- **Shape**: Frontmatter with dependency graph + narrative + deviations + self-check
+- **Lifecycle**: Created at plan completion → Read by subsequent plans in same phase
+- **Location**: `.planning/phases/XX-name/XX-YY-SUMMARY.md`
+- **Consumed by**: Orchestrator (progress), planner (context for future plans), `milestone-summary`
+
+### HANDOFF.json / .continue-here.md
+- **Shape**: Structured pause state (JSON machine-readable + Markdown human-readable)
+- **Lifecycle**: Created on pause → Consumed on resume → Replaced by next pause
+- **Location**: `.planning/HANDOFF.json` + `.planning/phases/XX-name/.continue-here.md` (or spike/deliberation path)
+- **Consumed by**: `resume-project` workflow
+
+---
+
+## Extended Artifacts
+
+### DISCUSSION-LOG.md (per-phase)
+- **Shape**: Audit trail of assumptions and corrections from discuss-phase
+- **Lifecycle**: Created at discussion time → Read-only audit record
+- **Location**: `.planning/phases/XX-name/XX-DISCUSSION-LOG.md`
+- **Consumed by**: Human review; not read by automated workflows
+
+### USER-PROFILE.md
+- **Shape**: Calibration tier and preferences profile
+- **Lifecycle**: Created by `profile-user` → Updated as preferences are observed
+- **Location**: `~/.claude/gsd-core/USER-PROFILE.md`
+- **Consumed by**: `discuss-phase-assumptions` (calibration tier), `plan-phase`
+
+### SPIKE.md / DESIGN.md (per-spike)
+- **Shape**: Research question + methodology + findings + recommendation
+- **Lifecycle**: Created → Investigated → Decided → Archived
+- **Location**: `.planning/spikes/SPIKE-NNN/`
+- **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
+
+### Spike README.md / MANIFEST.md (per-spike, via /gsd:spike)
+- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results
+- **Lifecycle**: Created by `/gsd:spike` → Verified → Wrapped up by `/gsd-spike-wrap-up`
+- **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md`
+- **Consumed by**: `/gsd-spike-wrap-up` for curation; `pause-work` for spike context handoff
+
+### Sketch README.md / MANIFEST.md / index.html (per-sketch)
+- **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML
+- **Lifecycle**: Created by `/gsd:sketch` → Evaluated → Wrapped up by `/gsd-sketch-wrap-up`
+- **Location**: `.planning/sketches/NNN-name/README.md`, `.planning/sketches/NNN-name/index.html`, `.planning/sketches/MANIFEST.md`
+- **Consumed by**: `/gsd-sketch-wrap-up` for curation; `pause-work` for sketch context handoff
+
+### WRAP-UP-SUMMARY.md (per wrap-up session)
+- **Shape**: Curation results, included/excluded items, feature/design area groupings
+- **Lifecycle**: Created by `/gsd-spike-wrap-up` or `/gsd-sketch-wrap-up`
+- **Location**: `.planning/spikes/WRAP-UP-SUMMARY.md` or `.planning/sketches/WRAP-UP-SUMMARY.md`
+- **Consumed by**: Project history; not read by automated workflows
+
+---
+
+## Standing Reference Artifacts
+
+### METHODOLOGY.md
+
+- **Shape**: Standing reference — reusable interpretive frameworks (lenses) that apply across phases
+- **Lifecycle**: Created → Active → Superseded (when a lens is replaced by a better one)
+- **Location**: `.planning/METHODOLOGY.md` (project-scoped, not phase-scoped)
+- **Contents**: Named lenses, each documenting:
+  - What it diagnoses (the class of problem it detects)
+  - What it recommends (the class of response it prescribes)
+  - When to apply (triggering conditions)
+  - Example: Bayesian updating, STRIDE threat modeling, Cost-of-delay prioritization
+- **Consumed by**:
+  - `discuss-phase-assumptions` — reads METHODOLOGY.md (if it exists) and applies active lenses
+    to the current assumption analysis before surfacing findings to the user
+  - `plan-phase` — reads METHODOLOGY.md to inform methodology selection for each plan
+  - `pause-work` — includes METHODOLOGY.md in the Required Reading section of `.continue-here.md`
+    so resuming agents inherit the project's analytical orientation
+
+**Why consumption matters:** A METHODOLOGY.md that no workflow reads is inert. The lenses only
+take effect when an agent loads them into its reasoning context before analysis. This is why
+both the discuss-phase-assumptions and pause-work workflows explicitly reference this file.
+
+**Example lens entry:**
+
+```markdown
+## Bayesian Updating
+
+**Diagnoses:** Decisions made with stale priors — assumptions formed early that evidence has since
+contradicted, but which remain embedded in the plan.
+
+**Recommends:** Before confirming an assumption, ask: "What evidence would make me change this?"
+If no evidence could change it, it's a belief, not an assumption. Flag for user review.
+
+**Apply when:** Any assumption carries Confident label but was formed before recent architectural
+changes, library upgrades, or scope corrections.
+```

package/gsd-core/references/auth-in-tests.md

@@ -0,0 +1,91 @@
+# Authentication in Integration & E2E Tests
+
+How-to reference for the thing AIs struggle with: auth in tests. Read this when a test needs an authenticated user. Goal: authenticate once, reuse the session, handle roles — without re-logging-in every test.
+
+## Core rules
+
+1. **Authenticate once, reuse the session.** Never drive the login UI in every test.
+2. **Drive the real login UI in exactly ONE test** (prove it works); **mint the session programmatically everywhere else.**
+3. **One account per parallel worker** to avoid collisions.
+4. **Secrets from env/CI**, never committed; gitignore the auth-state files (`.auth/`).
+
+## Playwright — setup project + storageState (canonical)
+
+```ts
+// auth.setup.ts — runs once, persists the authenticated state
+import { test as setup } from '@playwright/test';
+const authFile = 'playwright/.auth/user.json';
+setup('authenticate', async ({ request }) => {
+  await request.post('/api/login', { form: { user: process.env.E2E_USER!, password: process.env.E2E_PASS! } });
+  await request.storageState({ path: authFile });   // saves cookies + origin localStorage
+});
+```
+```ts
+// playwright.config.ts
+projects: [
+  { name: 'setup', testMatch: /.*\.setup\.ts/ },
+  { name: 'chromium', use: { ...devices['Desktop Chrome'], storageState: 'playwright/.auth/user.json' }, dependencies: ['setup'] },
+]
+```
+Opt a test OUT of auth (e.g. the login-page test): `test.use({ storageState: { cookies: [], origins: [] } })`.
+
+## Cypress — cy.session
+
+```js
+Cypress.Commands.add('login', (username, password) => {
+  cy.session([username, password], () => {                  // array id keys the cache per credential/role
+    cy.request('POST', '/api/login', { username, password })
+      .then(({ body }) => window.localStorage.setItem('authToken', body.token));
+  }, { validate() { cy.request('/api/whoami').its('status').should('eq', 200); },  // re-login when stale
+       cacheAcrossSpecs: true });                           // log in once for the whole run
+});
+```
+
+## Multi-role (RBAC) — one storageState per role
+
+```ts
+for (const role of ['admin', 'user']) {
+  setup(`auth ${role}`, async ({ request }) => {
+    await request.post('/api/login', { data: creds(role) });
+    await request.storageState({ path: `playwright/.auth/${role}.json` });
+  });
+}
+// pick a role per test: test.use({ storageState: 'playwright/.auth/admin.json' })
+// cross-role in ONE test: open two browser contexts, one per role file
+```
+
+## JWT vs cookie/session (different injection)
+
+| | JWT / Bearer | Cookie / session |
+|---|---|---|
+| **API test** | `request.newContext({ extraHTTPHeaders: { Authorization: 'Bearer '+t } })` | cookie jar / `Cookie` header |
+| **Browser test** | seed `localStorage` via `addInitScript` / storageState | `context.addCookies()` / storageState |
+| **CSRF** | bearer-in-header is CSRF-immune | forward a CSRF token in a custom header on mutating requests |
+
+## Parallel-safe accounts (one per worker)
+
+```ts
+const id = test.info().parallelIndex;          // 0..workers-1
+const file = `playwright/.auth/${id}.json`;    // reuse within the worker
+// acquireAccount(id) returns a pre-seeded account from a pool sized >= worker count
+```
+
+## Managed providers
+
+- **Clerk:** `clerk.signIn()` (server-side, bypasses MFA), `+clerk_test` emails, Testing Tokens for bot-detection bypass.
+- **Supabase:** `POST /auth/v1/token?grant_type=password`; inject the session into `localStorage` key `sb-<projectRef>-auth-token` (supabase-js v2; v1 used `supabase.auth.token` — detect at runtime).
+- **Auth.js / NextAuth:** a dev-only Credentials provider, or self-hosted Keycloak.
+
+## Mock vs real IdP
+
+- **Unit/integration:** mocking a 3rd-party IdP you can't seed (Auth0/Okta) is OK — but keep one real-token test (mocks skip signature validation).
+- **E2E:** use a real test instance (provider dev tenant, Firebase Auth emulator, self-hosted Keycloak/FusionAuth).
+- **MFA:** authenticate once and persist the session (sessions don't re-trigger MFA); generate the TOTP in setup, or `codegen --save-storage` once.
+
+## Anti-patterns
+
+- Logging in through the UI in every test (slow, flaky).
+- Sharing one account across parallel workers (collisions).
+- Committing tokens / auth-state files (gitignore `.auth/`).
+
+*Sources: Playwright & Cypress official auth docs; Clerk/Supabase/Auth.js testing guides; OWASP CSRF. Caveats: (1) `request.storageState()` **does** capture cookies including HttpOnly — but localStorage is only captured from a real browser context/page; an API-only context has no localStorage, so a token your client JS stores in localStorage won't be in it. (2) storageState is a point-in-time session — if tokens expire during a long run, regenerate it in the setup project rather than reusing a stale file (Cypress's `validate()` handles staleness; Playwright does not, so re-run setup). Always verify the saved state actually authenticates before trusting it.*