b64c5dae42
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Comprehensive architecture document for M4 quality enforcement pattern.
Problem (L-015 Evidence):
- AI agents claim done prematurely (60-70% complete)
- Defer work as "incremental" or "follow-up PRs"
- Identical language across sessions ("good enough for now")
- Happens even in YOLO mode with full permissions
- Cannot be fixed with instructions or prompting
Evidence:
- uConnect agent: 853 warnings deferred
- Mosaic Stack agent: 509 lint errors + 73 test failures deferred
- Both required manual override to continue
- Pattern observed across multiple agents and sessions
Solution: Non-AI Coordinator Pattern
- AI agents do the work
- Non-AI orchestrator enforces quality gates
- Gates are programmatic (build, lint, test, coverage)
- Agents cannot negotiate or bypass
- Forced continuation when gates fail
- Rejection with specific failure messages
Documentation Includes:
- Problem statement with evidence
- Why non-AI enforcement is necessary
- Complete architecture design
- Component specifications
- Quality gate types and configuration
- State machine and workflow
- Forced continuation prompt templates
- Integration points
- Monitoring and metrics
- Troubleshooting guide
- Implementation examples
Related Issues: #134-141 (M4-MoltBot)
Agents working on M4 issues now have complete context
and rationale without needing jarvis-brain access.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Architecture
Technical architecture and design principles for Mosaic Stack.
Chapters
- Overview — System design and component architecture
- Authentication — BetterAuth integration and OIDC flow
- Design Principles — PDA-friendly patterns and UX guidelines
Architecture Principles
- Type Safety First: Shared types prevent frontend/backend drift
- Multi-Tenant Ready: Row-level security with workspace isolation
- PDA-Friendly: Calm, stress-free language and visual design
- Modular: Plugin architecture for extensibility
Technology Decisions
Key architectural choices and their rationale:
- BetterAuth over Passport.js for modern authentication
- Prisma ORM for type-safe database access
- Monorepo with pnpm workspaces for code sharing
- PostgreSQL + pgvector for AI-ready data storage
Next Steps
- Review API for implementation details
- Check Development for workflow standards