@zigrivers/scaffold 2.1.1 → 2.28.1

package/knowledge/core/project-structure-patterns.md

@@ -0,0 +1,231 @@
+---
+name: project-structure-patterns
+description: Directory layout patterns by framework, module organization, and file placement rules
+topics: [project-structure, directory-layout, module-organization, file-placement, monorepo, colocation]
+---
+
+# Project Structure Patterns
+
+Directory structure is the physical manifestation of architectural decisions. A well-organized project communicates its architecture through the file tree alone — a new developer should understand the system's boundaries by reading directory names. This knowledge covers core layout patterns, framework-specific conventions, and the rules that keep structures clean as projects grow.
+
+## Summary
+
+### Core Patterns
+
+Three fundamental approaches to organizing source code:
+
+1. **Feature-Based (Vertical Slices)** — Group by business domain. Each feature directory contains its own components, services, tests, and types. Best for: domain-rich applications, teams organized by feature.
+2. **Layer-Based (Horizontal Layers)** — Group by technical concern. Separate directories for controllers, services, repositories, models. Best for: small projects, CRUD-heavy apps, teams organized by specialization.
+3. **Hybrid** — Feature-based at the top level, layer-based within each feature. Most common in practice. Combines domain clarity with technical organization.
+
+### The Co-Location Principle
+
+Files that change together should live together. A feature's component, styles, tests, types, and utilities belong in the same directory — not scattered across `components/`, `styles/`, `tests/`, `types/`, and `utils/`. Co-location reduces the cognitive cost of changes.
+
+### The Shared Code Rule
+
+Code belongs in a shared directory (`shared/`, `common/`, `lib/`) only when it has 2 or more consumers. A "shared" utility used by one feature is misplaced — it belongs in that feature's directory. Premature extraction into shared code creates coupling without benefit.
+
+### When to Restructure
+
+Restructure when: navigation becomes difficult (too many files in one directory), features are tangled (changing one feature touches many directories), or onboarding developers consistently get lost. Do not restructure for aesthetic reasons or because a blog post recommended a different layout.
+
+### Test Placement
+
+Co-located tests (`service.test.ts` next to `service.ts`) for unit tests — easy to find, move with refactors. Mirror directory (`tests/` mirroring `src/`) for integration and E2E tests that span modules.
+
+### Config vs. Application Code
+
+Tooling config files (`tsconfig.json`, `eslint.config.js`, `Makefile`) live at project root by convention. Application config (`src/config/`) holds runtime settings (database URLs, feature flags). Never mix the two locations.
+
+## Deep Guidance
+
+### Feature-Based Structure
+
+Feature-based organization maps directly to the product's domain model:
+
+```
+src/
+  features/
+    auth/
+      components/LoginForm.tsx, LoginForm.test.tsx
+      hooks/useAuth.ts, useAuth.test.ts
+      services/auth-service.ts, auth-service.test.ts
+      types.ts
+      index.ts           # public API barrel — other features import from here
+    billing/
+      components/, hooks/, services/, types.ts, index.ts
+  shared/
+    components/          # truly shared: Button, Modal, Input
+    hooks/               # truly shared: useDebounce, useLocalStorage
+    utils/               # truly shared: formatDate, validateEmail
+```
+
+**The index.ts barrel** defines each feature's public API. Other features import from `@/features/auth`, never from internal paths. This creates explicit boundaries — internal refactoring cannot break consumers.
+
+**When it breaks down**: Heavy cross-cutting concerns (every feature needs auth context, analytics, error boundaries). Solution: shared infrastructure lives in `shared/` or `infrastructure/`.
+
+### Layer-Based Structure
+
+Layer-based organization mirrors the technical architecture:
+
+```
+src/
+  controllers/auth-controller.ts, billing-controller.ts
+  services/auth-service.ts, billing-service.ts
+  repositories/user-repository.ts, invoice-repository.ts
+  models/user.ts, invoice.ts
+  middleware/auth-middleware.ts, logging-middleware.ts
+```
+
+Clear dependency direction: controllers depend on services, services on repositories, never reverse. Breaks down beyond ~20 files per directory — that signals the need for feature grouping.
+
+### Framework-Specific Patterns
+
+#### Next.js (App Router)
+
+```
+app/
+  layout.tsx, page.tsx
+  (auth)/login/page.tsx, signup/page.tsx    # route group (no URL segment)
+  dashboard/layout.tsx, page.tsx, settings/page.tsx
+  api/users/route.ts
+src/features/, src/shared/
+```
+
+Conventions: `page.tsx` defines routes, `layout.tsx` for nested layouts, `loading.tsx` for suspense, `error.tsx` for error boundaries. Route groups `(name)` organize without URL impact. Server Components default — mark `'use client'` explicitly.
+
+#### Express / Fastify
+
+```
+src/
+  routes/auth.routes.ts, index.ts     # route definitions (thin)
+  handlers/auth.handler.ts            # request/response logic
+  services/, repositories/, models/, middleware/
+  app.ts, server.ts
+```
+
+Separate routes from handlers. Routes define paths and middleware chains. Handlers contain logic and are independently testable.
+
+#### FastAPI
+
+```
+src/app/
+  routers/auth.py, billing.py
+  services/, repositories/
+  models/          # Pydantic schemas
+  db/              # SQLAlchemy models
+  core/config.py, security.py, dependencies.py
+  main.py
+```
+
+Convention: `routers/` not `routes/`. Pydantic models for API schemas, separate ORM models for database. Dependency injection via `Depends()`.
+
+#### Go
+
+```
+cmd/server/main.go, cli/main.go
+internal/
+  auth/handler.go, service.go, repository.go, handler_test.go
+  billing/...
+  platform/postgres/, redis/, http/
+pkg/validate/, money/
+```
+
+Convention: `cmd/` for entry points, `internal/` for private code (compiler-enforced), `pkg/` for reusable libraries. Flat package structure preferred.
+
+### Monorepo Patterns
+
+Use a monorepo when packages share types/utilities, you need atomic cross-package changes, or packages are tightly coupled. Do not use when packages are independently deployable with no shared code.
+
+```
+packages/
+  web/src/, package.json
+  api/src/, package.json
+  shared/src/, package.json
+  config/eslint-base.js, tsconfig-base.json
+package.json       # workspace configuration
+turbo.json         # build orchestration
+```
+
+Packages import from `@myorg/shared`, never from relative paths across package boundaries. Workspace resolution handles local development.
+
+### The Hybrid Pattern — Detailed Example
+
+The hybrid approach is the most practical for medium-to-large applications. Features at the top, layers within:
+
+```
+src/
+  features/
+    auth/
+      controller.ts      # HTTP handler / route handler
+      service.ts          # Business logic
+      repository.ts       # Data access
+      model.ts            # Domain types
+      service.test.ts     # Unit tests co-located
+      controller.test.ts
+    billing/
+      controller.ts
+      service.ts
+      repository.ts
+      model.ts
+      ...
+  shared/
+    middleware/           # Cross-cutting: auth, logging, rate-limit
+    utils/               # Truly shared utilities (2+ consumers)
+    types/               # Shared type definitions
+  config/                # Application configuration
+  app.ts                 # Application bootstrap
+  server.ts              # Server entry point
+```
+
+Each feature is self-contained. Adding a new feature means creating a new directory — no changes to existing features. Deleting a feature means removing one directory (plus cleanup of any shared references).
+
+### Config File Placement
+
+Config files live in the project root by universal convention: `package.json`, `tsconfig.json`, `eslint.config.js`, `pyproject.toml`, `go.mod`, `Makefile`, `Dockerfile`. Do not move them into a `config/` directory — tooling expects them at root. Application configuration (database URLs, feature flags) belongs in `src/config/`.
+
+### Generated File Handling
+
+Generated files (API clients, GraphQL types, migrations) need special treatment:
+- **Dedicated directory**: `src/generated/` or `__generated__/` — clearly non-hand-edited
+- **Linter exclusion**: `**/generated/**` excluded from lint configs
+- **Regeneration command**: `make generate` documented in CLAUDE.md
+- **Git decision**: Generated-from-committed-specs can be gitignored; generated-from-external-sources should be committed
+
+### Entry Points and Barrel Files
+
+**Entry points** (`main.ts`, `server.ts`, `index.ts` at project root, route files) are imported by the framework, not by other source files. Structure evals must exclude them from orphan detection.
+
+**Barrel files** (`index.ts` in feature directories) re-export the feature's public API. Rules:
+- One barrel per feature directory
+- Only re-export what other features need — internal utilities stay unexported
+- Never create barrel files in leaf directories (they add indirection without value)
+- Avoid circular dependencies by keeping barrel imports one-directional (features import from shared, never reverse)
+
+### Common Anti-Patterns
+
+**God Directories**: `src/utils/` has 47 files, `src/components/` has 93. Fix: move utilities into their consuming features. Only genuinely shared items (3+ consumers) stay in `shared/`.
+
+**Premature Abstraction into Shared**: Creating `shared/formatCurrency.ts` "because someone might need it later." Fix: enforce the 2+ consumer rule. Code enters `shared/` only when a second consumer actually needs it.
+
+**Inconsistent Depth**: 5-level nesting next to 2-level nesting. Fix: define maximum nesting depth (3-4 levels from `src/`). Deep nesting signals a feature should be split.
+
+**Orphaned Files**: Files not imported by anything and not entry points, accumulated during refactors. Fix: structure evals detect orphans in CI.
+
+### Migration Between Structures
+
+Moving from layer-based to feature-based (the most common migration):
+
+1. Create feature directories alongside existing layers
+2. Move one feature at a time — start with the most self-contained (fewest cross-feature dependencies)
+3. Update imports as you move — no redirect files
+4. Verify tests pass after each feature migration
+5. Delete empty layer directories once all features extracted
+6. Update `docs/project-structure.md`
+
+Move one feature per PR. Each PR leaves the project working with passing tests. Five small PRs over a week is safer than one massive PR touching every file.
+
+## See Also
+
+- [system-architecture](../core/system-architecture.md) — Architecture manifests in file structure

package/knowledge/core/review-step-template.md

@@ -0,0 +1,247 @@
+---
+name: review-step-template
+description: Shared template pattern for review pipeline steps including multi-model dispatch, finding severity, and resolution workflow
+topics: [review, template, multi-model, quality-gates, methodology]
+---
+
+# Review Step Template
+
+## Summary
+
+This entry documents the common structure shared by all 15+ review pipeline steps. Individual review steps customize this structure with artifact-specific failure modes and review passes, but the scaffolding is consistent across all reviews.
+
+**Purpose pattern**: Every review step targets domain-specific failure modes for a given artifact — not generic quality checks. Each pass has a specific focus, concrete checking instructions, and example findings.
+
+**Standard inputs**: Primary artifact being reviewed, upstream artifacts for cross-reference validation, `review-methodology` knowledge + artifact-specific review knowledge entry.
+
+**Standard outputs**: Review document (`docs/reviews/review-{artifact}.md`), updated primary artifact with P0/P1 fixes applied, and at depth 4+: multi-model artifacts (`codex-review.json`, `gemini-review.json`, `review-summary.md`) under `docs/reviews/{artifact}/`.
+
+**Finding severity**: P0 (blocking — must fix), P1 (significant — fix before implementation), P2 (improvement — fix if time permits), P3 (nitpick — log for later).
+
+**Methodology scaling**: Depth 1-2 runs top passes only (P0 focus). Depth 3 runs all passes. Depth 4-5 adds multi-model dispatch to Codex/Gemini with finding synthesis.
+
+**Mode detection**: First review runs all passes from scratch. Re-review preserves prior findings, marks resolved ones, and reports NEW/EXISTING/RESOLVED status.
+
+**Frontmatter conventions**: Reviews are order = creation step + 10, always include `review-methodology` in knowledge-base, and are never conditional.
+
+## Deep Guidance
+
+### Purpose Pattern
+
+Every review step follows the pattern:
+
+> Review **[artifact]** targeting **[domain]**-specific failure modes.
+
+The review does not check generic quality ("is this document complete?"). Instead, it runs artifact-specific passes that target the known ways that artifact type fails. Each pass has a specific focus, concrete checking instructions, and example findings.
+
+### Standard Inputs
+
+Every review step reads:
+- **Primary artifact**: The document being reviewed (e.g., `docs/domain-models.md`, `docs/api-contracts.md`)
+- **Upstream artifacts**: Documents the primary artifact was built from (e.g., PRD, domain models, ADRs) -- used for cross-reference validation
+- **Knowledge base entries**: `review-methodology` (shared process) + artifact-specific review knowledge (e.g., `review-api-design`, `review-database-design`)
+
+### Standard Outputs
+
+Every review step produces:
+- **Review document**: `docs/reviews/review-{artifact}.md` -- findings organized by pass, with severity and trace information
+- **Updated artifact**: The primary artifact with fixes applied for P0/P1 findings
+- **Depth 4+ multi-model artifacts** (when methodology depth >= 4):
+  - `docs/reviews/{artifact}/codex-review.json` -- Codex independent review findings
+  - `docs/reviews/{artifact}/gemini-review.json` -- Gemini independent review findings
+  - `docs/reviews/{artifact}/review-summary.md` -- Synthesized findings from all models
+
+### Finding Severity Levels
+
+All review steps use the same four-level severity scale:
+
+| Level | Name | Meaning | Action |
+|-------|------|---------|--------|
+| P0 | Blocking | Cannot proceed to downstream steps without fixing | Must fix before moving on |
+| P1 | Significant | Downstream steps can proceed but will encounter problems | Fix before implementation |
+| P2 | Improvement | Artifact works but could be better | Fix if time permits |
+| P3 | Nitpick | Style or preference | Log for future cleanup |
+
+### Finding Format
+
+Each finding includes:
+- **Pass**: Which review pass discovered it (e.g., "Pass 3 -- Auth/AuthZ Coverage")
+- **Priority**: P0-P3
+- **Location**: Specific section, line, or element in the artifact
+- **Issue**: What is wrong, with concrete details
+- **Impact**: What goes wrong downstream if this is not fixed
+- **Recommendation**: Specific fix, not just "fix this"
+- **Trace**: Link back to upstream artifact that establishes the requirement (e.g., "PRD Section 3.2 -> Architecture DF-005")
+
+### Example Finding
+
+```markdown
+### Finding F-003 (P1)
+- **Pass**: Pass 2 — Entity Coverage
+- **Location**: docs/domain-models/order.md, Section "Order Aggregate"
+- **Issue**: Order aggregate does not include a `cancellationReason` field, but PRD
+  Section 4.1 requires cancellation reason tracking for analytics.
+- **Impact**: Implementation will lack cancellation reason; analytics pipeline will
+  receive null values, causing dashboard gaps.
+- **Recommendation**: Add `cancellationReason: CancellationReason` value object to
+  Order aggregate with enum values: USER_REQUEST, PAYMENT_FAILED, OUT_OF_STOCK,
+  ADMIN_ACTION.
+- **Trace**: PRD §4.1 → User Story US-014 → Domain Model: Order Aggregate
+```
+
+### Review Document Structure
+
+Every review output document follows a consistent structure:
+
+```markdown
+  # Review: [Artifact Name]
+
+  **Date**: YYYY-MM-DD
+  **Methodology**: deep | mvp | custom:depth(N)
+  **Status**: INITIAL | RE-REVIEW
+  **Models**: Claude | Claude + Codex | Claude + Codex + Gemini
+
+  ## Findings Summary
+  - Total findings: N (P0: X, P1: Y, P2: Z, P3: W)
+  - Passes run: N of M
+  - Artifacts checked: [list]
+
+  ## Findings by Pass
+
+  ### Pass 1 — [Pass Name]
+  [Findings listed by severity, highest first]
+
+  ### Pass 2 — [Pass Name]
+  ...
+
+  ## Resolution Log
+  | Finding | Severity | Status | Resolution |
+  |---------|----------|--------|------------|
+  | F-001   | P0       | RESOLVED | Fixed in commit abc123 |
+  | F-002   | P1       | EXISTING | Deferred — tracked in ADR-015 |
+
+  ## Multi-Model Synthesis (depth 4+)
+  ### Convergent Findings
+  [Issues found by 2+ models — high confidence]
+
+  ### Divergent Findings
+  [Issues found by only one model — requires manual triage]
+```
+
+### Methodology Scaling Pattern
+
+Review steps scale their thoroughness based on the methodology depth setting:
+
+### Depth 1-2 (MVP/Minimal)
+- Run only the highest-impact passes (typically passes 1-3)
+- Single-model review only
+- Focus on P0 findings; skip P2/P3
+- Abbreviated finding descriptions
+
+### Depth 3 (Standard)
+- Run all review passes
+- Single-model review
+- Report all severity levels
+- Full finding descriptions with trace information
+
+### Depth 4-5 (Comprehensive)
+- Run all review passes
+- Multi-model dispatch: send the artifact to Codex and Gemini for independent analysis
+- Synthesize findings from all models, flagging convergent findings (multiple models found the same issue) as higher confidence
+- Cross-artifact consistency checks against all upstream documents
+- Full finding descriptions with detailed trace and impact analysis
+
+### Depth Scaling Example
+
+At depth 2 (MVP), a domain model review might produce:
+
+```markdown
+  # Review: Domain Models (MVP)
+  ## Findings Summary
+  - Total findings: 3 (P0: 1, P1: 2)
+  - Passes run: 3 of 10
+  ## Findings
+  ### F-001 (P0) — Missing aggregate root for Payment bounded context
+  ### F-002 (P1) — Order entity lacks status field referenced in user stories
+  ### F-003 (P1) — No domain event defined for order completion
+```
+
+At depth 5 (comprehensive), the same review would run all 10 passes, dispatch to
+Codex and Gemini, and produce a full synthesis with 15-30 findings across all
+severity levels.
+
+### Mode Detection Pattern
+
+Every review step checks whether this is a first review or a re-review:
+
+**First review**: No prior review document exists. Run all passes from scratch.
+
+**Re-review**: A prior review document exists (`docs/reviews/review-{artifact}.md`). The step:
+1. Reads the prior review findings
+2. Checks which findings were addressed (fixed in the artifact)
+3. Marks resolved findings as "RESOLVED" rather than removing them
+4. Runs all passes again looking for new issues or regressions
+5. Reports findings as "NEW", "EXISTING" (still unfixed), or "RESOLVED"
+
+This preserves review history and makes progress visible.
+
+### Resolution Workflow
+
+The standard workflow from review to resolution:
+
+1. **Review**: Run the review step, producing findings
+2. **Triage**: Categorize findings by severity; confirm P0s are genuine blockers
+3. **Fix**: Update the primary artifact to address P0 and P1 findings
+4. **Re-review**: Run the review step again in re-review mode
+5. **Verify**: Confirm all P0 findings are resolved; P1 findings are resolved or have documented justification for deferral
+6. **Proceed**: Move to the next pipeline phase
+
+For depth 4+ reviews, the multi-model dispatch happens in both the initial review and the re-review, ensuring fixes do not introduce new issues visible to other models.
+
+### Frontmatter Pattern
+
+Review steps follow a consistent frontmatter structure:
+
+```yaml
+---
+name: review-{artifact}
+description: "Review {artifact} for completeness, consistency, and downstream readiness"
+phase: "{phase-slug}"
+order: {N}20  # Reviews are always 10 after their creation step
+dependencies: [{creation-step}]
+outputs: [docs/reviews/review-{artifact}.md, docs/reviews/{artifact}/review-summary.md, docs/reviews/{artifact}/codex-review.json, docs/reviews/{artifact}/gemini-review.json]
+conditional: null
+knowledge-base: [review-methodology, review-{artifact-domain}]
+---
+```
+
+Key conventions:
+- Review steps always have order = creation step order + 10
+- Primary output uses `review-` prefix; multi-model directory uses bare artifact name
+- Knowledge base always includes `review-methodology` plus a domain-specific entry
+- Reviews are never conditional — if the creation step ran, the review runs
+
+### Common Anti-Patterns
+
+### Reviewing Without Upstream Context
+Running a review without loading the upstream artifacts that define requirements.
+The review cannot verify traceability if it does not have the PRD, domain models,
+or ADRs that establish what the artifact should contain.
+
+### Severity Inflation
+Marking everything as P0 to force immediate action. This undermines the severity
+system and causes triage fatigue. Reserve P0 for genuine blockers where downstream
+steps will fail or produce incorrect output.
+
+### Fix Without Re-Review
+Applying fixes to findings without re-running the review. Fixes can introduce new
+issues or incompletely address the original finding. Always re-review after fixes.
+
+### Ignoring Convergent Multi-Model Findings
+When multiple models independently find the same issue, it has high confidence.
+Dismissing convergent findings without strong justification undermines the value
+of multi-model review.
+
+### Removing Prior Findings
+Deleting findings from a re-review output instead of marking them RESOLVED. This
+loses review history and makes it impossible to track what was caught and fixed.

package/knowledge/core/{security-review.md → security-best-practices.md}

@@ -1,5 +1,5 @@
 ---
-name: security-review
+name: security-best-practices
 description: OWASP Top 10, authentication, authorization, data protection, and threat modeling
 topics: [security, owasp, authentication, authorization, threat-modeling, secrets-management, dependency-auditing]
 ---
@@ -521,3 +521,7 @@ Protect against compromised dependencies:
 **No rate limiting.** Login endpoints with unlimited attempts allow brute-force password attacks. API endpoints with no rate limits allow denial of service. Fix: implement rate limiting on all public endpoints. Start with conservative limits. Use exponential backoff for authentication failures.
 
 **Ignoring dependency vulnerabilities.** Running `npm audit` shows 47 vulnerabilities but nobody addresses them because "they're all low severity." Fix: set a policy and enforce it in CI. Critical and high vulnerabilities block deployment. Medium vulnerabilities have a SLA for resolution.
+
+## See Also
+
+- [operations-runbook](../core/operations-runbook.md) — Logging and monitoring sensitive data