@devran-ai/kit 4.1.0

package/.agent/rules/architecture.md

@@ -0,0 +1,111 @@
+# Architecture Rules
+
+> **Priority**: HIGH — Enforced in design reviews
+> **Scope**: All workspaces — universal architectural constraints
+
+---
+
+## Architecture Principles
+
+| Principle                | Enforcement                                                   |
+| :----------------------- | :------------------------------------------------------------ |
+| Separation of Concerns   | Each module has a single, well-defined responsibility         |
+| Dependency Direction     | Dependencies ALWAYS point inward — domain never imports infra |
+| Contract-First Design    | Define API contracts before implementation begins             |
+| Explicit Over Implicit   | Configuration, dependencies, and boundaries must be explicit  |
+| Composition Over Inherit | Prefer composition and dependency injection over inheritance  |
+
+---
+
+## Boundary Enforcement
+
+- **NEVER** import backend code from frontend or vice versa
+- **NEVER** skip architectural layers — each layer imports only from the layer directly below
+- **NEVER** hold direct object references across aggregate or module boundaries — use IDs
+- Shared types and contracts are defined at the API boundary and replicated per consumer
+- Cross-module communication uses events or explicit service interfaces, not direct coupling
+
+---
+
+## Project Structure
+
+Projects should follow one of these organizational patterns:
+
+| Pattern          | When to Use                                              |
+| :--------------- | :------------------------------------------------------- |
+| **Monorepo**     | Multiple apps sharing code (Turborepo, Nx, Rush)         |
+| **Polyrepo**     | Independent services with separate lifecycles            |
+| **Modular Mono** | Single deployable with clear bounded context separation  |
+
+> **Customization**: Project-specific structure decisions should be documented in `decisions/` as Architecture Decision Records (ADRs).
+
+---
+
+## Layered Architecture
+
+```
+Thin Routes / Controllers → Service Layer → Models / Data Access
+                              ↕
+                          Domain Logic
+```
+
+| Layer            | Responsibility                            | Rules                                              |
+| :--------------- | :---------------------------------------- | :------------------------------------------------- |
+| Routes           | HTTP handling, auth enforcement           | MAX 10 lines per handler, delegate to services      |
+| Services         | Business logic, validation, orchestration | Pure functions where possible, fully testable       |
+| Models / Data    | Database schema, relationships            | ORM-managed, migration-controlled                   |
+| Schemas          | Request/response contracts                | Validated models, explicit field constraints         |
+
+---
+
+## Database Conventions
+
+- **Migrations** for ALL schema changes — no manual SQL in production
+- Table names: `snake_case`, plural (`users`, `funnel_events`)
+- Column names: `snake_case`
+- Always include: `id` (UUID recommended), `created_at`, `updated_at`
+- Foreign keys: `<entity>_id` naming convention
+- Indexes: create for all foreign keys and frequent query columns
+- Soft deletes preferred over hard deletes for audit-sensitive data
+
+---
+
+## API Design Principles
+
+| Principle            | Standard                                                    |
+| :------------------- | :---------------------------------------------------------- |
+| Versioning           | URL-prefix (`/api/v1/`) or header-based — be consistent    |
+| Methods              | Standard HTTP methods and status codes (RESTful)            |
+| Response Format      | All endpoints return validated, structured JSON             |
+| Pagination           | Offset-based (`skip`/`limit`) or cursor-based — documented |
+| Error Format         | `{ "detail": "Human-readable message" }` minimum           |
+| Rate Limiting        | Documented per endpoint, enforced server-side               |
+
+---
+
+## Architecture Decision Records
+
+When making significant architectural decisions, document them using ADRs in the `decisions/` directory:
+
+- Choosing between architectural approaches (monolith vs microservices)
+- Selecting a technology (database, framework, library)
+- Establishing a pattern (event sourcing vs CRUD)
+- Making a trade-off (consistency vs availability)
+
+ADR format: `decisions/adr-NNN-<decision-title>.md`
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/architecture/SKILL.md` — deep architectural patterns (DDD, Clean Architecture, 12-Factor, SOLID)
+- **Agent**: `.agent/agents/architect.md` — architecture review process and checklists
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                                |
+| :------ | :--------- | :----------------------------------------------------- |
+| 1.0.0   | 2026-03-16 | Initial generic architecture enforcement rules for kit |
+

package/.agent/rules/coding-style.md

@@ -0,0 +1,75 @@
+# Coding Style Rules
+
+> **Priority**: HIGH — Enforced in reviews
+> **Scope**: All workspaces (TypeScript + Python)
+
+---
+
+## TypeScript (Frontend & Backend)
+
+- **STRICT** mode enabled (`strict: true` in `tsconfig.json`)
+- **NO** `any` type usage — use `unknown` with type guards when needed
+- **EXPLICIT** return types on all exported functions
+- **Zod** for runtime validation of API responses and form input
+
+### Naming Conventions
+
+| Entity                     | Convention        | Example               |
+| :------------------------- | :---------------- | :-------------------- |
+| Variables & functions      | `camelCase`       | `getUserProfile`      |
+| Types, interfaces, classes | `PascalCase`      | `FunnelEventResponse` |
+| Constants                  | `SCREAMING_SNAKE` | `MAX_RETRY_COUNT`     |
+| React components           | `PascalCase`      | `ThemeToggle`         |
+| CSS custom properties      | `--kebab-case`    | `--color-primary`     |
+| File names (components)    | `PascalCase.tsx`  | `NavDrawer.tsx`       |
+| File names (utilities)     | `camelCase.ts`    | `useScrollState.ts`   |
+
+---
+
+## Python (Backend)
+
+- **Type hints** on ALL function signatures (parameters + return)
+- **Pydantic** models for all request/response validation
+- **NO** bare `except` clauses — always catch specific exceptions
+- `snake_case` for functions, variables, modules
+- `PascalCase` for classes (SQLAlchemy models, Pydantic schemas)
+- **f-strings** preferred over `.format()` or `%`
+
+---
+
+## File Organization (Universal)
+
+| Metric                  | Limit        | Enforcement                       |
+| :---------------------- | :----------- | :-------------------------------- |
+| Lines per file          | MAX 800      | Hard limit                        |
+| Lines per function      | MAX 50       | Hard limit                        |
+| Nesting depth           | MAX 4 levels | Hard limit                        |
+| Parameters per function | MAX 5        | Soft limit — use objects beyond 5 |
+
+---
+
+## Immutability
+
+- **PREFER** `const` over `let` (TypeScript)
+- **USE** spread operator for state updates
+- **AVOID** direct mutation — return new objects/arrays
+- Python: favor tuple unpacking and `dataclass(frozen=True)` where applicable
+
+---
+
+## Import Order
+
+### TypeScript
+
+1. React / Next.js built-ins
+2. Third-party packages
+3. Internal aliases (`@/components`, `@/lib`)
+4. Relative imports
+5. Type-only imports (`import type { ... }`)
+
+### Python
+
+1. Standard library
+2. Third-party packages
+3. Local application imports
+4. Blank line between each group

package/.agent/rules/documentation.md

@@ -0,0 +1,74 @@
+# Documentation Rules
+
+> **Priority**: HIGH — Enforced in reviews
+
+---
+
+## Document Hierarchy
+
+| File                     | Role                         | Update Frequency    |
+| :----------------------- | :--------------------------- | :------------------ |
+| `docs/ARCHITECTURE.md`   | System design, tech stack    | On architecture changes |
+| `docs/ROADMAP.md`        | Sprint tracking (SSOT)       | Every session start/end |
+| `docs/CHANGELOG.md`      | Shipped work log             | Every session end       |
+| `.agent/session-context.md` | Session handoff context   | Every session end       |
+| `.agent/session-state.json` | Machine-readable metadata | Every session end       |
+
+---
+
+## ROADMAP.md as SSOT
+
+**`docs/ROADMAP.md` is the Single Source of Truth for sprint tracking.**
+
+- **NEVER** track task status in any other file
+- **ALWAYS** read ROADMAP.md at session start before doing anything
+- **UPDATE** ROADMAP.md at session end with completed/in-progress items
+- **PRESENT** sprint state to user after loading
+
+---
+
+## CHANGELOG.md Format
+
+Follow [Keep a Changelog](https://keepachangelog.com/):
+
+```markdown
+## [Sprint X] — YYYY-MM-DD
+
+### Added
+- New feature description
+
+### Changed
+- Modified behavior description
+
+### Fixed
+- Bug fix description
+```
+
+---
+
+## Inline Documentation
+
+- **WHY over WHAT**: Comments explain rationale, not mechanics
+- **Complex logic**: Every non-obvious algorithm needs a comment explaining WHY it exists
+- **API docs**: Public APIs documented with JSDoc/docstrings
+- **No stale comments**: If code changes, comments must change too
+
+---
+
+## Preservation Rule
+
+**No valuable content shall be silently deleted.**
+
+- When updating files, apply changes **additively**
+- If content must be removed, explicitly document what was removed and why
+- Never silently drop sections when rewriting files
+
+---
+
+## Cross-Reference Integrity
+
+**When referencing actions in other files, complete those actions in the same commit.**
+
+- **Reference = Action**: "Move to X.md" means update X.md immediately
+- **Completion Check**: Verify all referenced actions are completed
+- **No broken links**: All file references must point to existing files

package/.agent/rules/git-workflow.md

@@ -0,0 +1,140 @@
+# Git Workflow Rules — GitFlow
+
+> **Priority**: HIGH — Enforced by hooks
+> **Strategy**: GitFlow with `dev` as integration branch, `main` as production
+
+> [!CAUTION]
+> **PUSH POLICY**: NEVER push commits during implementation or task work.
+> Commits are **local-only** until the user explicitly requests the **session-end protocol**.
+> The pre-push hook runs the full LOCAL-CI-GATE (lint, type-check, tests, build) which takes 60-160 seconds.
+> Premature pushes waste time and block the agent. Only push once, at session end, after all work is verified.
+
+---
+
+## Branch Strategy
+
+```
+main (production — protected, release-only)
+ └── dev (integration — all features merge here first)
+      ├── feat/add-python-agent
+      ├── fix/cli-init-error
+      ├── refactor/loading-engine
+      └── docs/update-readme
+```
+
+### Branch Types
+
+| Branch | Base | Merges Into | Purpose |
+| :--- | :--- | :--- | :--- |
+| `main` | — | — | Production releases only. Never commit directly. |
+| `dev` | `main` | `main` (via release PR) | Integration branch. All feature work targets here. |
+| `feat/*` | `dev` | `dev` | New features |
+| `fix/*` | `dev` | `dev` | Bug fixes |
+| `refactor/*` | `dev` | `dev` | Code restructuring |
+| `docs/*` | `dev` | `dev` | Documentation |
+| `test/*` | `dev` | `dev` | Test additions |
+| `chore/*` | `dev` | `dev` | Maintenance |
+| `hotfix/*` | `main` | `main` AND `dev` | Critical production fixes |
+
+### Branch Naming Convention
+
+```
+type/short-description
+```
+
+Examples:
+- `feat/pr-toolkit-v2`
+- `fix/windows-eperm-retry`
+- `hotfix/security-patch-auth`
+- `chore/bump-vitest-v4`
+
+---
+
+## Merge Rules
+
+### Feature → dev
+
+1. Create feature branch from `dev`
+2. Develop and commit locally (conventional commits)
+3. Push feature branch to remote
+4. Create PR targeting `dev`
+5. Wait for CI checks to pass
+6. Wait for reviewer approval (gemini-code-assist or human)
+7. Squash-merge into `dev`
+
+### dev → main (Release)
+
+1. Ensure `dev` is stable (all CI green, no WIP)
+2. Create release PR: `dev` → `main`
+3. PR title: `release: vX.Y.Z`
+4. Wait for ALL CI checks to pass
+5. Wait for human review approval
+6. Merge (no squash — preserve history)
+7. Tag the release: `git tag vX.Y.Z`
+8. Run `npm publish` from `main`
+9. Merge `main` back into `dev` (sync release commit)
+
+### hotfix → main
+
+1. Create `hotfix/*` branch from `main`
+2. Fix the issue with minimal changes
+3. Create PR targeting `main`
+4. After merge, merge `main` back into `dev` to sync the hotfix
+
+---
+
+## Commit Format
+
+```
+type(scope): description
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+
+| Type | Use |
+| :--- | :--- |
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation |
+| `refactor` | Code restructuring |
+| `test` | Test additions |
+| `chore` | Maintenance |
+| `perf` | Performance optimization |
+| `ci` | CI/CD changes |
+
+---
+
+## Before Commit
+
+- [ ] All tests pass (`npm test`)
+- [ ] Lint passes
+- [ ] Build succeeds
+- [ ] No secrets in code
+- [ ] Counts synced if components added/removed
+
+## Pull Requests
+
+- **REQUIRE** code review (gemini-code-assist + human)
+- **INCLUDE** test coverage
+- **LINK** to issue/ticket
+- **TARGET** `dev` for features/fixes, `main` for releases/hotfixes only
+- **NEVER** create a PR from `main` or `dev` directly
+- **CONVENTIONAL** title format: `type(scope): description`
+
+---
+
+## Session-End Protocol (Commit & Push)
+
+When the user says "Commit & Push" or similar:
+
+1. **Branch Check**: Verify you're on a feature branch (not `main` or `dev`)
+2. **Stage Changes**: `git add` relevant files (never `git add -A` blindly)
+3. **Commit**: Use conventional commit message
+4. **Push**: Push feature branch to remote with `-u` flag
+5. **Create PR**: Target `dev` branch (not `main`)
+6. **Report**: Share PR URL and wait for CI + reviewer approval
+7. **Do NOT merge**: User decides when to merge after reviews pass

package/.agent/rules/quality-gate.md

@@ -0,0 +1,117 @@
+# Quality Gate Rules
+
+> **Priority**: HIGH — Enforced before implementation of new features and refactors
+> **Scope**: All workspaces — applies to `feat()` and `refactor()` tasks only
+
+---
+
+## Scope Filter
+
+| Task Type                         | Quality Gate Required? |
+| :-------------------------------- | :--------------------- |
+| `feat()` — new features           | ✅ Required            |
+| `refactor()` — structural changes | ✅ Required            |
+| `fix()` — bug fixes               | ❌ Skip                |
+| `chore()` — maintenance           | ❌ Skip                |
+| `docs()` — documentation          | ❌ Skip                |
+| `test()` — test additions         | ❌ Skip                |
+
+---
+
+## Pre-Execution Research Checklist
+
+Before implementing any in-scope task, **ALL** items must be completed. If any item is incomplete, execution is forbidden.
+
+### ☐ 1. Market Research Completed
+
+- Analyze **minimum 5** competitors or market leaders in the feature domain
+- Document how each implements the same or similar feature
+- Identify user adoption drivers: UX simplicity, accuracy, speed, transparency
+
+### ☐ 2. Outdated Pattern Verification
+
+- Verify the proposed approach does not use deprecated, abandoned, or criticized patterns
+- If outdated → propose a modern, evidence-based alternative (mandatory)
+- Document which patterns are considered harmful or legacy
+
+### ☐ 3. Baseline Parity Validation
+
+- Confirm the project **meets or exceeds** the current market baseline
+- Gaps must be explicitly listed with severity assessment
+- No gap left unaddressed without documented justification
+
+### ☐ 4. Enhancement Definition
+
+- Define exactly how the project **improves upon** the market baseline
+- Improvement must be intentional and documented
+- Consider: transparency, ethical automation, user-centricity, measurable outcomes
+
+### ☐ 5. Ethics & Automation Risk Assessment
+
+- Evaluate: privacy implications, AI bias risks, automation safety, user autonomy
+- Mitigation strategies must be documented for each identified risk
+- Data protection compliance must be considered for data-touching features
+
+### ☐ 6. Implementation Plan Prepared
+
+- Structured plan ready before execution begins
+- Plan includes research summary, key insights, risks, execution steps
+- Plan reviewed and approved before implementation may begin
+
+---
+
+## Enhancement Principle
+
+| Scenario                                    | Required Action                  |
+| :------------------------------------------ | :------------------------------- |
+| Competitors offer a standard                | **Meet or exceed** it            |
+| Competitors use unethical automation        | **Reject and improve**           |
+| Feature can be more transparent             | **Enhance by default**           |
+| Feature can be more user-centric            | **Enhance by default**           |
+| Feature can offer measurable outcomes       | **Enhance by default**           |
+
+**Never replicate patterns without improvement.**
+
+---
+
+## Cross-Cutting Deference
+
+Quality gate enforcement defers to specialized rules for domain-specific checks:
+
+- **Security**: See `rules/security.md` for input validation, auth, data protection
+- **Testing**: See `rules/testing.md` for coverage requirements, test types
+- **Code Quality**: See `rules/coding-style.md` for naming, file limits, immutability
+- **Documentation**: See `rules/documentation.md` for doc hierarchy, SSOT
+
+---
+
+## Reject & Escalate Rules
+
+| Condition                                   | Action                                 |
+| :------------------------------------------ | :------------------------------------- |
+| No market research provided                 | ❌ Reject — enforce research protocol  |
+| Clearly outdated or harmful patterns        | ❌ Reject — propose modern alternative |
+| Below-market standard solutions             | ❌ Reject — document gap               |
+| Ethics, privacy, or automation safety risks | ❌ Reject — document mitigation        |
+| Bypassing research ("just implement it")    | ❌ Reject — enforce protocol           |
+
+### Escalation Response
+
+> "This task cannot proceed in its current form, as it does not meet quality and market standards. Below are the identified risks and gaps. A revised, modern alternative is proposed."
+
+---
+
+## Related Resources
+
+- **Workflow**: `.agent/workflows/quality-gate.md` — step-by-step research procedure
+- **Skill**: `.agent/skills/brainstorming/SKILL.md` — Socratic questioning patterns
+- **Next Step**: After approval, proceed to `/plan` for implementation planning
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                           |
+| :------ | :--------- | :------------------------------------------------ |
+| 1.0.0   | 2026-03-16 | Initial generic quality gate protocol for kit     |
+

package/.agent/rules/security.md

@@ -0,0 +1,67 @@
+# Security Rules
+
+> **Priority**: CRITICAL — Inviolable
+
+---
+
+## Secrets Management
+
+- **NEVER** hardcode secrets in source code
+- **ALWAYS** use environment variables via project config
+- **BLOCK** commits containing `sk-`, `api_key=`, `password=`, `secret=`
+- **MAINTAIN** `.env.example` with all required variables (values redacted)
+- `.env` files MUST be in `.gitignore` — no exceptions
+
+---
+
+## Input Validation
+
+- **Backend**: Pydantic/Zod models validate ALL request bodies and query params
+- **Frontend**: Zod schemas validate ALL form inputs and API responses
+- **NEVER** trust client-side data — re-validate server-side
+- **SANITIZE** all input before database writes or AI pipeline consumption
+- **LIMIT** payload sizes (request body, file uploads)
+
+---
+
+## Authentication & Authorization
+
+- **JWT** with separate access and refresh token secrets
+- **REQUIRE** authentication on all sensitive endpoints
+- Rate limiting: **5 login attempts/minute**, **10 API calls/hour/user** (adjust per project)
+- **ROTATE** tokens on logout and password change
+- Refresh tokens: httpOnly cookies, NOT localStorage
+
+---
+
+## Data Protection
+
+> Projects processing PII must comply with applicable data protection regulations (GDPR, CCPA, etc.).
+
+| Principle          | Implementation                                  |
+| :----------------- | :---------------------------------------------- |
+| Data minimization  | Collect only what's needed for the feature      |
+| Purpose limitation | Document why each data field is collected       |
+| Right to erasure   | User account deletion cascades to all user data |
+| Data encryption    | PII encrypted at rest (database-level)          |
+| Transfer security  | HTTPS enforced for all API communication        |
+| Consent            | Explicit opt-in for AI processing of user data  |
+| Retention          | Define and enforce data retention periods       |
+
+---
+
+## API Security
+
+- **CORS**: Restrict to known origins only (project domains + localhost)
+- **Headers**: Set security headers (`X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security`)
+- **Logging**: Log auth failures, never log passwords or tokens
+- **Dependencies**: Run `npm audit` and `pip audit` before releases
+
+---
+
+## AI Pipeline Safety
+
+- **NEVER** send raw user PII to external AI providers without anonymization review
+- **LOG** all AI API calls for audit trail (sans PII)
+- **VALIDATE** AI outputs before presenting to users (hallucination guards)
+- **RATE LIMIT** AI provider calls to prevent cost overruns

package/.agent/rules/sprint-tracking.md

@@ -0,0 +1,103 @@
+# Sprint Tracking Protocol
+
+> **Priority**: CRITICAL — Enforced by session checklists
+> **SSOT**: `docs/ROADMAP.md` is the **only** place where task status is tracked
+
+---
+
+## Core Principle
+
+> **`docs/ROADMAP.md` is the Single Source of Truth.**
+> No task status lives outside this file. No exceptions.
+> If it's not in ROADMAP.md, it doesn't exist as a tracked item.
+
+---
+
+## Session Start Protocol
+
+1. **Read** `docs/ROADMAP.md` — load current sprint state
+2. **Identify** in-progress `[/]` items from last session
+3. **Present** sprint state summary to user before starting work
+4. **Validate** against `docs/ARCHITECTURE.md` for structural context
+5. **Begin** work only after user confirms direction
+
+---
+
+## Session End Protocol
+
+1. **Update** `docs/ROADMAP.md` with completed `[x]` and in-progress `[/]` items
+2. **Sync** `docs/CHANGELOG.md` with shipped work from this session
+3. **Update** `.agent/session-context.md` with handoff notes for next session
+4. **Update** `.agent/session-state.json` with machine-readable metadata
+5. **Verify** no duplicate entries exist (ROADMAP ↔ CHANGELOG ↔ session-context)
+6. **Commit** all tracking files together in a single atomic commit
+
+---
+
+## Mid-Session Updates
+
+- **Mark items `[/]`** when starting work on them
+- **Mark items `[x]`** immediately when completing them
+- **Add sub-items** under parent tasks as they're discovered
+- **NEVER** mark items complete without verification
+
+---
+
+## Sprint Lifecycle States
+
+| Marker | Meaning      | When to Use                          |
+| :----- | :----------- | :----------------------------------- |
+| `[ ]`  | Not started  | Task exists but work hasn't begun    |
+| `[/]`  | In progress  | Actively being worked on             |
+| `[x]`  | Completed    | Done and verified                    |
+| `[-]`  | Cancelled    | Intentionally dropped with reason    |
+
+---
+
+## Sprint Question Protocol
+
+When the user asks about sprint status:
+
+1. **ALWAYS** read `docs/ROADMAP.md` first
+2. **PRESENT** the current state from the file
+3. **NEVER** answer from memory — the file is the source of truth
+4. If file is stale or missing, inform user and offer to create/update it
+
+---
+
+## Reject & Escalate Rules
+
+### REJECT (Agent must refuse)
+
+- Tracking task status in `session-context.md` instead of `ROADMAP.md`
+- Creating duplicate task lists in multiple files
+- Marking tasks complete without verification
+- Updating CHANGELOG without updating ROADMAP
+
+### ESCALATE (Agent must ask user)
+
+- Sprint scope changes (adding/removing major items)
+- Changing sprint deadlines
+- Deferring critical-path items to next sprint
+- Architecture changes that affect sprint estimates
+
+---
+
+## Cultural References
+
+> These organizations exemplify the sprint discipline we enforce:
+
+| Company    | Practice We Adopt                          |
+| :--------- | :----------------------------------------- |
+| Stripe     | Ship fast, measure everything, iterate     |
+| Amazon     | Two-pizza teams, ownership, bias for action |
+| Anthropic  | Safety-first, no shortcuts on quality      |
+| Linear     | Opinionated tooling, consistent execution  |
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                    |
+| :------ | :--------- | :----------------------------------------- |
+| 1.0.0   | 2026-03-15 | Initial sprint tracking protocol for kit   |