mosaic/bootstrap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync local Mosaic changes

Browse Source
This commit is contained in:
Jason Woltje
2026-02-21 09:55:34 -06:00
parent 1e4eefeca3
commit e3ec3e32e5
82 changed files with 5398 additions and 1969 deletions
Download Patch File Download Diff File Expand all files Collapse all files

0
guides/authentication.md → guides/AUTHENTICATION.md
View File

19
guides/backend.md → guides/BACKEND.md
View File

@@ -47,7 +47,7 @@
- Use project's established auth pattern
- Validate tokens on every request
- Check permissions before operations
- See `~/.config/mosaic/guides/authentication.md` for details
- See `~/.config/mosaic/guides/AUTHENTICATION.md` for details
## Testing Requirements (TDD)
1. Write tests BEFORE implementation
@@ -73,18 +73,19 @@ class TestResourceEndpoint:
## Code Style
- Follow Google Style Guide for your language
- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
- Use linter/formatter from project configuration
- Keep functions focused and small
- Document complex business logic
### TypeScript Quick Rules (see typescript.md for full guide)
- **NO `any`** — define explicit types always
- **NO lazy `unknown`** — only for error catches and external data with validation
- **Explicit return types** on all exported functions
- **Explicit parameter types** always
- **Interface for DTOs** — never inline object types
- **Typed errors** — use custom error classes
### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
- **NO `any`** — define explicit types always
- **NO lazy `unknown`** — only for error catches and external data with validation
- **Explicit return types** on all exported functions
- **Explicit parameter types** always
- **DTO files are REQUIRED** for module/API boundaries (`*.dto.ts`)
- **Interface for DTOs** — never inline object types
- **Typed errors** — use custom error classes
## Performance
- Use database connection pooling

486
guides/BOOTSTRAP.md Executable file
View File

@@ -0,0 +1,486 @@
# Project Bootstrap Guide
> Load this guide when setting up a new project for AI-assisted development.
## Overview
This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) can work on it effectively. Proper bootstrapping ensures:
1. Agents understand the project structure and conventions
2. Orchestration works correctly with quality gates
3. Independent code review and security review are configured
4. Issue tracking is consistent across projects
5. Documentation standards and API contracts are enforced from day one
6. PRD requirements are established before coding begins
7. Branching/merging is consistent: `branch -> main` via PR with squash-only merges
8. Steered-autonomy execution is enabled so agents can run end-to-end with escalation-only human intervention
## Quick Start
```bash
# Automated bootstrap (recommended)
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "my-project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo"
# Or manually using templates
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export TASK_PREFIX="MP"
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
```
---
## Step 0: Enforce Sequential-Thinking MCP (Hard Requirement)
`sequential-thinking` MCP must be installed and configured before project bootstrapping.
```bash
# Auto-configure sequential-thinking MCP for installed runtimes
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking
# Verification-only check
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
```
If this step fails, STOP and remediate Mosaic runtime configuration before continuing.
---
## Step 1: Detect Project Type
Check what files exist in the project root to determine the type:
| File Present | Project Type | Template |
|---|---|---|
| `package.json` + `pnpm-workspace.yaml` + NestJS+Next.js | NestJS + Next.js Monorepo | `projects/nestjs-nextjs/` |
| `pyproject.toml` + `manage.py` | Django | `projects/django/` |
| `pyproject.toml` (no Django) | Python (generic) | Generic template |
| `package.json` (no monorepo) | Node.js (generic) | Generic template |
| Other | Generic | Generic template |
```bash
# Auto-detect project type
detect_project_type() {
if [[ -f "pnpm-workspace.yaml" ]] && [[ -f "turbo.json" ]]; then
# Check for NestJS + Next.js
if grep -q "nestjs" package.json 2>/dev/null && grep -q "next" package.json 2>/dev/null; then
echo "nestjs-nextjs"
return
fi
fi
if [[ -f "manage.py" ]] && [[ -f "pyproject.toml" ]]; then
echo "django"
return
fi
if [[ -f "pyproject.toml" ]]; then
echo "python"
return
fi
if [[ -f "package.json" ]]; then
echo "nodejs"
return
fi
echo "generic"
}
```
---
## Step 2: Create AGENTS.md (Primary Project Contract)
`AGENTS.md` is the primary project-level contract for all agent runtimes.
It defines project-specific requirements, quality gates, patterns, and testing expectations.
### Using a Tech-Stack Template
```bash
# Set variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="Multi-tenant SaaS platform"
export PROJECT_DIR="my-project"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export TASK_PREFIX="MP"
# Use tech-stack-specific template if available
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
else
envsubst < "$HOME/.config/mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
fi
```
### Using the Generic Template
```bash
# Set all required variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export PROJECT_DIR="my-project"
export SOURCE_DIR="src"
export CONFIG_FILES="pyproject.toml / package.json"
export FRONTEND_STACK="N/A"
export BACKEND_STACK="Python / FastAPI"
export DATABASE_STACK="PostgreSQL"
export TESTING_STACK="pytest"
export DEPLOYMENT_STACK="Docker"
export BUILD_COMMAND="pip install -e ."
export TEST_COMMAND="pytest tests/"
export LINT_COMMAND="ruff check ."
export TYPECHECK_COMMAND="mypy ."
export QUALITY_GATES="ruff check . && mypy . && pytest tests/"
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```
### Required Sections
Every AGENTS.md should contain:
1. **Project description** — One-line summary
2. **Quality gates** — Commands that must pass
3. **Codebase patterns** — Reusable implementation rules
4. **Common gotchas** — Non-obvious constraints
5. **Testing approaches** — Project-specific test strategy
6. **Testing policy** — Situational-first validation and risk-based TDD
7. **Orchestrator integration** — Task prefix, worker checklist
8. **Documentation contract** — Required documentation gates and update expectations
9. **PRD requirement** — `docs/PRD.md` or `docs/PRD.json` required before coding
---
## Step 3: Create Runtime Context File (Runtime-Specific)
Runtime context files are runtime adapters. They are not the primary project contract.
Use `CLAUDE.md` for Claude runtime compatibility. Use other runtime adapters as required by your environment.
Claude runtime mandate (HARD RULE):
- `CLAUDE.md` MUST explicitly instruct Claude agents to read and use `AGENTS.md`.
- `CLAUDE.md` MUST treat `AGENTS.md` as the authoritative project-level contract.
- If `AGENTS.md` and runtime wording conflict, `AGENTS.md` project rules win.
```bash
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
else
envsubst < "$HOME/.config/mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
fi
```
### Required Runtime Sections
Every runtime context file should contain:
1. **AGENTS handoff rule** — Runtime MUST direct agents to read/use `AGENTS.md`
2. **Conditional documentation loading** — Required guide loading map
3. **Technology stack** — Runtime-facing architecture summary
4. **Repository structure** — Important paths
5. **Development workflow** — Build/test/lint/typecheck commands
6. **Issue tracking** — Issue and commit conventions
7. **Code review** — Required review process
8. **Runtime notes** — Runtime-specific behavior references
9. **Branch and merge policy** — Trunk workflow (`branch -> main` via PR, squash-only)
10. **Autonomy and escalation policy** — Agent owns coding/review/PR/release/deploy lifecycle
---
## Step 4: Create Directory Structure
```bash
# Create standard directories
mkdir -p docs/scratchpads
mkdir -p docs/templates
mkdir -p docs/reports/qa-automation/pending
mkdir -p docs/reports/qa-automation/in-progress
mkdir -p docs/reports/qa-automation/done
mkdir -p docs/reports/qa-automation/escalated
mkdir -p docs/reports/deferred
mkdir -p docs/tasks
mkdir -p docs/releases
mkdir -p docs/USER-GUIDE docs/ADMIN-GUIDE docs/DEVELOPER-GUIDE docs/API
# Documentation baseline files
touch docs/USER-GUIDE/README.md
touch docs/ADMIN-GUIDE/README.md
touch docs/DEVELOPER-GUIDE/README.md
touch docs/API/OPENAPI.yaml
touch docs/API/ENDPOINTS.md
touch docs/SITEMAP.md
# PRD baseline file (requirements source before coding)
cp ~/.config/mosaic/templates/docs/PRD.md.template docs/PRD.md
# TASKS baseline file (canonical tracking)
cp ~/.config/mosaic/templates/docs/TASKS.md.template docs/TASKS.md
# Deployment baseline file (target/platform/runbook)
touch docs/DEPLOYMENT.md
```
Documentation root hygiene (HARD RULE):
- Keep `docs/` root clean.
- Store reports in `docs/reports/`, archived task artifacts in `docs/tasks/`, releases in `docs/releases/`, and scratchpads in `docs/scratchpads/`.
- Do not place ad-hoc report files directly under `docs/`.
---
## Step 5: Initialize Repository Labels & Milestones
```bash
# Use the init script
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
# Or manually create standard labels
~/.config/mosaic/rails/git/issue-create.sh # (labels are created on first use)
```
### Standard Labels
| Label | Color | Purpose |
|-------|-------|---------|
| `epic` | `#3E4B9E` | Large feature spanning multiple issues |
| `feature` | `#0E8A16` | New functionality |
| `bug` | `#D73A4A` | Defect fix |
| `task` | `#0075CA` | General work item |
| `documentation` | `#0075CA` | Documentation updates |
| `security` | `#B60205` | Security-related |
| `breaking` | `#D93F0B` | Breaking change |
### Initial Milestone (Hard Rule)
Create the first pre-MVP milestone at `0.0.1`.
Reserve `0.1.0` for the MVP release milestone.
```bash
~/.config/mosaic/rails/git/milestone-create.sh -t "0.0.1" -d "Pre-MVP - Foundation Sprint"
# Create when MVP scope is complete and release-ready:
~/.config/mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
```
---
## Step 5b: Configure Main Branch Protection (Hard Rule)
Apply equivalent settings in Gitea, GitHub, or GitLab:
1. Protect `main` from direct pushes.
2. Require pull requests to merge into `main`.
3. Require required CI/status checks to pass before merge.
4. Require code review approval before merge.
5. Allow **squash merge only** for PRs into `main` (disable merge commits and rebase merges for `main`).
This enforces one merge strategy across human and agent workflows.
---
## Step 6: Set Up CI/CD Review Pipeline
### Woodpecker CI
```bash
# Copy Codex review pipeline
mkdir -p .woodpecker/schemas
cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
cp ~/.config/mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
# Add codex_api_key secret to Woodpecker CI dashboard
```
### GitHub Actions
For GitHub repos, use the official Codex GitHub Action instead:
```yaml
# .github/workflows/codex-review.yml
uses: openai/codex-action@v1
```
### Python Package Publishing (Gitea PyPI)
If the project publishes Python packages, use Gitea's PyPI registry.
```bash
# Build and publish
python -m pip install --upgrade build twine
python -m build
python -m twine upload \
--repository-url "https://GITEA_HOST/api/packages/ORG/pypi" \
--username "$GITEA_USERNAME" \
--password "$GITEA_TOKEN" \
dist/*
```
Use the same `gitea_username` and `gitea_token` CI secrets used for container and npm publishing.
---
## Step 7: Verify Bootstrap
After bootstrapping, verify everything works:
```bash
# Check files exist
ls AGENTS.md docs/scratchpads/
ls docs/reports/qa-automation/pending docs/reports/deferred docs/tasks docs/releases
ls docs/USER-GUIDE/README.md docs/ADMIN-GUIDE/README.md docs/DEVELOPER-GUIDE/README.md
ls docs/API/OPENAPI.yaml docs/API/ENDPOINTS.md docs/SITEMAP.md
ls docs/PRD.md
ls docs/TASKS.md
# Verify AGENTS.md has required sections
grep -c "Quality Gates" AGENTS.md
grep -c "Orchestrator Integration" AGENTS.md
grep -c "Testing Approaches" AGENTS.md
grep -c "Testing Policy" AGENTS.md
grep -c "Documentation Contract" AGENTS.md
grep -c "PRD Requirement" AGENTS.md
# Verify runtime context file has required sections
if [[ -f CLAUDE.md ]]; then
grep -c "AGENTS.md" CLAUDE.md
grep -c "Conditional Documentation Loading" CLAUDE.md
grep -c "Technology Stack" CLAUDE.md
grep -c "Code Review" CLAUDE.md
elif [[ -f RUNTIME.md ]]; then
grep -c "Conditional Documentation Loading" RUNTIME.md
grep -c "Technology Stack" RUNTIME.md
grep -c "Code Review" RUNTIME.md
else
echo "Missing runtime context file (CLAUDE.md or RUNTIME.md)" >&2
exit 1
fi
# Run quality gates from AGENTS.md
# (execute the command block under "Quality Gates")
# Test Codex review (if configured)
~/.config/mosaic/rails/codex/codex-code-review.sh --help
# Verify sequential-thinking MCP remains configured
~/.config/mosaic/bin/mosaic-ensure-sequential-thinking --check
```
---
## Available Templates
### Generic Templates
| Template | Path | Purpose |
|----------|------|---------|
| `AGENTS.md.template` | `~/.config/mosaic/templates/agent/` | Primary project agent contract |
| `CLAUDE.md.template` | `~/.config/mosaic/templates/agent/` | Runtime compatibility context (Claude) |
| `DOCUMENTATION-CHECKLIST.md` | `~/.config/mosaic/templates/docs/` | Documentation completion gate |
| `PRD.md.template` | `~/.config/mosaic/templates/docs/` | Requirements source template |
| `TASKS.md.template` | `~/.config/mosaic/templates/docs/` | Canonical task and issue tracking template |
### Tech-Stack Templates
| Stack | Path | Includes |
|-------|------|----------|
| NestJS + Next.js | `~/.config/mosaic/templates/agent/projects/nestjs-nextjs/` | AGENTS.md + runtime context template |
| Django | `~/.config/mosaic/templates/agent/projects/django/` | AGENTS.md + runtime context template |
### Orchestrator Templates
| Template | Path | Purpose |
|----------|------|---------|
| `tasks.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Task tracking |
| `orchestrator-learnings.json.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Variance tracking |
| `phase-issue-body.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Git provider issue body |
| `scratchpad.md.template` | `~/src/jarvis-brain/docs/templates/` | Per-task working doc |
### Variables Reference
| Variable | Description | Example |
|----------|-------------|---------|
| `${PROJECT_NAME}` | Human-readable project name | "Mosaic Stack" |
| `${PROJECT_DESCRIPTION}` | One-line description | "Multi-tenant platform" |
| `${PROJECT_DIR}` | Directory name | "mosaic-stack" |
| `${PROJECT_SLUG}` | Python package slug | "mosaic_stack" |
| `${REPO_URL}` | Git remote URL | "https://git.mosaicstack.dev/mosaic/stack" |
| `${TASK_PREFIX}` | Orchestrator task prefix | "MS" |
| `${SOURCE_DIR}` | Source code directory | "src" or "apps" |
| `${QUALITY_GATES}` | Quality gate commands | "pnpm typecheck && pnpm lint && pnpm test" |
| `${BUILD_COMMAND}` | Build command | "pnpm build" |
| `${TEST_COMMAND}` | Test command | "pnpm test" |
| `${LINT_COMMAND}` | Lint command | "pnpm lint" |
| `${TYPECHECK_COMMAND}` | Type check command | "pnpm typecheck" |
| `${FRONTEND_STACK}` | Frontend technologies | "Next.js + React" |
| `${BACKEND_STACK}` | Backend technologies | "NestJS + Prisma" |
| `${DATABASE_STACK}` | Database technologies | "PostgreSQL" |
| `${TESTING_STACK}` | Testing technologies | "Vitest + Playwright" |
| `${DEPLOYMENT_STACK}` | Deployment technologies | "Docker" |
| `${CONFIG_FILES}` | Key config files | "package.json, tsconfig.json" |
---
## Bootstrap Scripts
### init-project.sh
Full project bootstrap with interactive and flag-based modes:
```bash
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "My Project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo" \
--prefix "MP" \
--description "Multi-tenant platform"
```
### init-repo-labels.sh
Initialize standard labels and the first pre-MVP milestone:
```bash
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
```
---
## Checklist
After bootstrapping, verify:
- [ ] `AGENTS.md` exists and is the primary project contract
- [ ] Runtime context file exists (`CLAUDE.md` or `RUNTIME.md`)
- [ ] `docs/scratchpads/` directory exists
- [ ] `docs/reports/qa-automation/pending` directory exists
- [ ] `docs/reports/deferred/` directory exists
- [ ] `docs/tasks/` directory exists
- [ ] `docs/releases/` directory exists
- [ ] `docs/USER-GUIDE/README.md` exists
- [ ] `docs/ADMIN-GUIDE/README.md` exists
- [ ] `docs/DEVELOPER-GUIDE/README.md` exists
- [ ] `docs/API/OPENAPI.yaml` exists
- [ ] `docs/API/ENDPOINTS.md` exists
- [ ] `docs/SITEMAP.md` exists
- [ ] `docs/PRD.md` or `docs/PRD.json` exists
- [ ] `docs/TASKS.md` exists and is ready for active tracking
- [ ] `docs/DEPLOYMENT.md` exists with target platform and rollback notes
- [ ] `sequential-thinking` MCP is configured and verification check passes
- [ ] Git labels created (epic, feature, bug, task, etc.)
- [ ] Initial pre-MVP milestone created (0.0.1)
- [ ] MVP milestone reserved for release (0.1.0)
- [ ] `main` is protected from direct pushes
- [ ] PRs into `main` are required
- [ ] Merge method for `main` is squash-only
- [ ] Quality gates run successfully
- [ ] `.env.example` exists (if project uses env vars)
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
- [ ] Python publish path configured in CI (if project ships Python packages)
- [ ] Codex review scripts accessible (`~/.config/mosaic/rails/codex/`)

122
guides/code-review.md → guides/CODE-REVIEW.md Normal file → Executable file
View File

@@ -1,28 +1,57 @@
# Code Review Guide
# Code Review Guide
## Hard Requirement
If an agent modifies source code, code review is REQUIRED before completion.
Do not mark code-change tasks done until review is completed and blockers are resolved or explicitly tracked.
If code/config/API contract/auth behavior changed and required docs are missing, this is a BLOCKER.
If tests pass but acceptance criteria are not verified by situational evidence, this is a BLOCKER.
If implementation diverges from `docs/PRD.md` or `docs/PRD.json` without PRD updates, this is a BLOCKER.
Merge strategy enforcement (HARD RULE):
- PR target for delivery is `main`.
- Direct pushes to `main` are prohibited.
- Merge to `main` MUST be squash-only.
- Use `~/.config/mosaic/rails/git/pr-merge.sh -n {PR_NUMBER} -m squash` (or PowerShell equivalent).
## Review Checklist
## Review Checklist
### 1. Correctness
- [ ] Code does what the issue/PR description says
- [ ] Code aligns with active PRD requirements
- [ ] Acceptance criteria are mapped to concrete verification evidence
- [ ] Edge cases are handled
- [ ] Error conditions are managed properly
- [ ] No obvious bugs or logic errors
### 1. Correctness
- [ ] Code does what the issue/PR description says
- [ ] Edge cases are handled
- [ ] Error conditions are managed properly
- [ ] No obvious bugs or logic errors
### 2. Security
- [ ] No hardcoded secrets or credentials
- [ ] Input validation at boundaries
- [ ] SQL injection prevention (parameterized queries)
- [ ] XSS prevention (output encoding)
- [ ] Authentication/authorization checks present
- [ ] Sensitive data not logged
- [ ] Secrets follow Vault structure (see `docs/vault-secrets-structure.md`)
### 2a. OWASP Coverage (Required)
- [ ] OWASP Top 10 categories were reviewed for change impact
- [ ] Access control checks verified on protected actions
- [ ] Cryptographic handling validated (keys, hashing, TLS assumptions)
- [ ] Injection risks reviewed for all untrusted inputs
- [ ] Security misconfiguration risks reviewed (headers, CORS, defaults)
- [ ] Dependency/component risk reviewed (known vulnerable components)
- [ ] Authentication/session flows reviewed for failure paths
- [ ] Logging/monitoring preserves detection without leaking sensitive data
### 2. Security
- [ ] No hardcoded secrets or credentials
- [ ] Input validation at boundaries
- [ ] SQL injection prevention (parameterized queries)
- [ ] XSS prevention (output encoding)
- [ ] Authentication/authorization checks present
- [ ] Sensitive data not logged
- [ ] Secrets follow Vault structure (see `docs/vault-secrets-structure.md`)
### 3. Testing
- [ ] Tests exist for new functionality
- [ ] Tests cover happy path AND error cases
- [ ] Coverage meets 85% minimum
- [ ] Tests are readable and maintainable
- [ ] No flaky tests introduced
### 3. Testing
- [ ] Tests exist for new functionality
- [ ] Tests cover happy path AND error cases
- [ ] Situational tests cover all impacted change surfaces (primary gate)
- [ ] Tests validate required behavior/outcomes, not only internal implementation details
- [ ] TDD was applied when required by `~/.config/mosaic/guides/QA-TESTING.md`
- [ ] Coverage meets 85% minimum
- [ ] Tests are readable and maintainable
- [ ] No flaky tests introduced
### 4. Code Quality
- [ ] Follows Google Style Guide for the language
@@ -32,21 +61,27 @@
- [ ] Clear naming for variables and functions
- [ ] No dead code or commented-out code
### 4a. TypeScript Strict Typing (see `typescript.md`)
- [ ] **NO `any` types** — explicit types required everywhere
- [ ] **NO lazy `unknown`** — only for error catches with immediate narrowing
- [ ] **Explicit return types** on all exported/public functions
- [ ] **Explicit parameter types** — never implicit any
- [ ] **No type assertions** (`as Type`) — use type guards instead
- [ ] **No non-null assertions** (`!`) — use proper null handling
- [ ] **Interfaces for objects** — not inline types
- [ ] **Discriminated unions** for variant types
### 4a. TypeScript Strict Typing (see `TYPESCRIPT.md`)
- [ ] **NO `any` types** — explicit types required everywhere
- [ ] **NO lazy `unknown`** — only for error catches with immediate narrowing
- [ ] **Explicit return types** on all exported/public functions
- [ ] **Explicit parameter types** — never implicit any
- [ ] **No type assertions** (`as Type`) — use type guards instead
- [ ] **No non-null assertions** (`!`) — use proper null handling
- [ ] **Interfaces for objects** — not inline types
- [ ] **Discriminated unions** for variant types
- [ ] **DTO files used at boundaries** — module/API contracts are in `*.dto.ts`, not inline payload types
### 5. Documentation
- [ ] Complex logic has explanatory comments
- [ ] Public APIs are documented
- [ ] README updated if needed
- [ ] Breaking changes noted
### 5. Documentation
- [ ] Complex logic has explanatory comments
- [ ] Required docs updated per `~/.config/mosaic/guides/DOCUMENTATION.md`
- [ ] Public APIs are documented
- [ ] Private/internal APIs are documented
- [ ] API input/output schemas are documented
- [ ] API permissions/auth requirements are documented
- [ ] Site map updates are present when navigation changed
- [ ] README updated if needed
- [ ] Breaking changes noted
### 6. Performance
- [ ] No obvious N+1 queries
@@ -59,7 +94,9 @@
- [ ] No unnecessary new dependencies
- [ ] Dependency versions pinned appropriately
## Review Process
## Review Process
Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` whenever code/API/auth/infra changes are present.
### Getting Context
```bash
@@ -94,8 +131,9 @@ Use parameterized queries instead:
This pattern appears in 3 places. A shared helper would reduce duplication.
```
## After Review
1. Update issue with review status
2. If changes requested, assign back to author
3. If approved, note approval in issue comments
4. For merges, ensure CI passes first
## After Review
1. Update issue with review status
2. If changes requested, assign back to author
3. If approved, note approval in issue comments
4. For merges, ensure CI passes first
5. Merge PR to `main` with squash strategy only

132
guides/DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,132 @@
# Documentation Standard (MANDATORY)
This guide defines REQUIRED documentation behavior for all Mosaic projects.
If code, API contracts, auth, or infrastructure changes, documentation updates are REQUIRED before completion.
## Hard Rules
1. Documentation is a delivery gate. Missing required documentation is a BLOCKER.
2. `docs/PRD.md` or `docs/PRD.json` is REQUIRED as the project requirements source before coding begins.
3. API documentation is OpenAPI-first. `docs/API/OPENAPI.yaml` (or `.json`) is the canonical API contract.
4. Public and private/internal endpoints MUST be documented.
5. API input and output schemas MUST be documented.
6. API authentication and permissions MUST be documented per endpoint.
7. A current site map MUST exist at `docs/SITEMAP.md`.
8. Documentation updates MUST be committed in the same logical change set as the code/API change.
9. Generated publishing output (Docusaurus/VitePress/MkDocs artifacts) is not canonical unless the project explicitly declares it canonical.
10. `docs/` root MUST stay clean. Reports and working artifacts MUST be stored in dedicated subdirectories, not dumped at `docs/` root.
## Required Documentation Structure
```text
docs/
PRD.md (or PRD.json)
TASKS.md (active orchestrator tracking, when orchestrator is used)
SITEMAP.md
USER-GUIDE/
ADMIN-GUIDE/
DEVELOPER-GUIDE/
API/
OPENAPI.yaml
ENDPOINTS.md
scratchpads/
reports/
tasks/
releases/
templates/ (optional)
```
Minimum requirements:
- `docs/PRD.md` or `docs/PRD.json`: authoritative requirements source for implementation and testing.
- `docs/USER-GUIDE/`: End-user workflows, feature behavior, common troubleshooting.
- `docs/ADMIN-GUIDE/`: Configuration, deployment, operations, incident/recovery procedures.
- `docs/DEVELOPER-GUIDE/`: Architecture, local setup, contribution/testing workflow, design constraints.
- `docs/API/OPENAPI.yaml`: API SSOT for all HTTP endpoints.
- `docs/API/ENDPOINTS.md`: Human-readable index for API endpoints, permissions, and change notes.
- `docs/SITEMAP.md`: Navigation index for all user/admin/developer/API documentation pages.
- `docs/reports/`: Review outputs, QA automation reports, deferrals, and audit artifacts.
- `docs/tasks/`: Archived task snapshots and orchestrator learnings.
- `docs/releases/`: Release notes and release-specific documentation.
- `docs/scratchpads/`: Active task-level working notes.
## Root Hygiene Rule (MANDATORY)
Allowed root documentation files are intentionally limited:
1. `docs/PRD.md` or `docs/PRD.json`
2. `docs/TASKS.md` (active milestone only, when task orchestration is in use)
3. `docs/SITEMAP.md`
4. `docs/README.md` (optional index)
All other docs MUST be placed in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`, `docs/API/`, guide books).
## Artifact Placement Rules
| Artifact Type | REQUIRED Location |
|---|---|
| Code review reports, QA reports, audits | `docs/reports/<category>/` |
| Deferred error lists / unresolved findings | `docs/reports/deferred/` |
| Archived milestone task snapshots | `docs/tasks/` |
| Orchestrator learnings JSON | `docs/tasks/orchestrator-learnings.json` |
| Release notes | `docs/releases/` |
| Active scratchpads | `docs/scratchpads/` |
## API Documentation Contract (OpenAPI-First)
For every API endpoint, documentation MUST include:
1. visibility: `public` or `private/internal`
2. method and path
3. endpoint purpose
4. request/input schema
5. response/output schema(s)
6. auth method and required permission/role/scope
7. error status codes and behavior
If OpenAPI cannot fully express an internal constraint, document it in `docs/API/ENDPOINTS.md`.
## Book/Chapter/Page Structure
Use this structure for every guide:
1. Book: one root guide folder (`USER-GUIDE`, `ADMIN-GUIDE`, `DEVELOPER-GUIDE`)
2. Chapter: one subdirectory per topic area
3. Page: one focused markdown file per concern
Required index files:
1. `docs/USER-GUIDE/README.md`
2. `docs/ADMIN-GUIDE/README.md`
3. `docs/DEVELOPER-GUIDE/README.md`
Each index file MUST link to all chapters and pages in that book.
## Situational Documentation Matrix
| Change Surface | REQUIRED Documentation Updates |
|---|---|
| New feature or behavior change | User guide + developer guide + sitemap |
| API endpoint added/changed/removed | OpenAPI + API endpoint index + sitemap |
| Auth/RBAC/permission change | API auth/permission docs + admin guide + developer guide |
| Database schema/migration change | Developer guide + admin operational notes if runbook impact |
| CI/CD or deployment change | Admin guide + developer guide |
| Incident, recovery, or security control change | Admin guide runbook + security notes + sitemap |
## Publishing Target Rule (MANDATORY)
If the user does not specify documentation publishing target, the agent MUST ask:
1. Publish in-app (embedded docs)
2. Publish on external docs platform (for example: Docusaurus, VitePress, MkDocs)
Default behavior before publishing decision:
- Keep canonical docs in-repo under `docs/`.
- Do not assume external publishing platform.
## Completion Gate
You MUST NOT declare completion until all required documentation updates are done.
Use `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md` as the final gate.

4
guides/frontend.md → guides/FRONTEND.md
View File

@@ -49,12 +49,12 @@ describe('ComponentName', () => {
## Code Style
- Follow Google JavaScript/TypeScript Style Guide
- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
- Use ESLint/Prettier configuration from project
- Prefer functional components over class components (React)
- TypeScript strict mode is REQUIRED, not optional
### TypeScript Quick Rules (see typescript.md for full guide)
### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
- **NO `any`** — define explicit types always
- **NO lazy `unknown`** — only for error catches and external data with validation
- **Explicit return types** on all exported functions

71
guides/infrastructure.md → guides/INFRASTRUCTURE.md
View File

@@ -97,10 +97,10 @@ readinessProbe:
periodSeconds: 3
```
## CI/CD Pipelines
### Pipeline Stages
1. **Lint**: Code style and static analysis
## CI/CD Pipelines
### Pipeline Stages
1. **Lint**: Code style and static analysis
2. **Test**: Unit and integration tests
3. **Build**: Compile and package
4. **Scan**: Security and vulnerability scanning
@@ -109,10 +109,65 @@ readinessProbe:
### Pipeline Security
- Use secrets management (not hardcoded)
- Pin action/image versions
- Implement approval gates for production
- Audit pipeline access
## Monitoring & Logging
- Implement approval gates for production
- Audit pipeline access
## Steered-Autonomous Deployment (Hard Rule)
In lights-out mode, the agent owns deployment end-to-end when deployment is in scope.
The human is escalation-only for missing access, hard policy conflicts, or irreversible risk.
### Deployment Target Selection
1. Use explicit target from `docs/PRD.md` / `docs/PRD.json` or `docs/DEPLOYMENT.md`.
2. If unspecified, infer from existing project config/integration.
3. If multiple targets exist, choose the target already wired in CI/CD and document rationale.
### Supported Targets
- **Portainer**: Deploy via configured stack webhook/API, then verify service health and container status.
- **Coolify**: Trigger deployment via Coolify API/webhook, then verify deployment status and endpoint health.
- **Vercel**: Deploy via `vercel` CLI or connected Git integration, then verify preview/production URL health.
- **Other SaaS providers**: Use provider CLI/API/runbook with the same validation and rollback gates.
### Image Tagging and Promotion (Hard Rule)
For containerized deployments:
1. Build immutable image tags: `sha-<shortsha>` and `v{base-version}-rc.{build}`.
2. Use mutable environment tags only as pointers: `testing`, optional `staging`, and `prod`.
3. Deploy by immutable digest, not by mutable tag alone.
4. Promote the exact tested digest between environments (no rebuild between testing and prod).
5. Do not use `latest` or `dev` as deployment references.
Blue-green is the default strategy for production promotion.
Canary is allowed only when automated SLO/error-rate gates and auto-rollback triggers are implemented.
### Post-Deploy Validation (REQUIRED)
1. Health endpoints return expected status.
2. Critical smoke tests pass in target environment.
3. Running version and digest match the promoted release candidate.
4. Observability signals (errors/latency) are within expected thresholds.
### Rollback Rule
If post-deploy validation fails:
1. Execute rollback/redeploy-safe path immediately.
2. Mark deployment as blocked in `docs/TASKS.md`.
3. Record failure evidence and next remediation step in scratchpad and release notes.
### Registry Retention and Cleanup
Cleanup MUST be automated.
- Keep all final release tags (`vX.Y.Z`) indefinitely.
- Keep active environment digests (`prod`, `testing`, and active blue/green slots).
- Keep recent RC tags (`vX.Y.Z-rc.N`) based on retention window.
- Remove stale `sha-*` and RC tags outside retention window if they are not actively deployed.
## Monitoring & Logging
### Logging Standards
- Use structured logging (JSON)

27
guides/MEMORY.md Normal file
View File

@@ -0,0 +1,27 @@
# Memory and Retention Rules
## Hard Rules
1. You MUST store learned operational memory in `~/.config/mosaic/memory`.
2. You MUST NOT store durable memory in runtime-native memory silos.
3. You MUST write concise, reusable learnings that help future agents.
4. You MUST track active execution state in project documentation, not ad-hoc text files.
## Runtime-Native Memory Silos (FORBIDDEN for Durable Memory)
| Runtime | Native silo (forbidden for durable memory) | Required durable location |
|---|---|---|
| Claude Code | `~/.claude/projects/*/memory/` | `~/.config/mosaic/memory/` + project `docs/` |
| Codex | Runtime session/native memory under `~/.codex/` | `~/.config/mosaic/memory/` + project `docs/` |
| OpenCode | Runtime session/native memory under `~/.config/opencode/` | `~/.config/mosaic/memory/` + project `docs/` |
Treat runtime-native memory as volatile implementation detail. Do not rely on it for long-term project continuity.
## Project Continuity Files (MANDATORY)
| File | Purpose | Location |
|---|---|---|
| `docs/PRD.md` or `docs/PRD.json` | Source of requirements for planning, coding, testing, and review | Project `docs/` |
| `docs/TASKS.md` | Canonical tracking for tasks, milestones, issues, status, and blockers | Project `docs/` |
| `docs/scratchpads/<task>.md` | Task-specific working memory and verification evidence | Project `docs/scratchpads/` |
| `AGENTS.md` | Reusable local patterns and gotchas | Any working directory |

8
guides/orchestrator-learnings.md → guides/ORCHESTRATOR-LEARNINGS.md
View File

@@ -2,11 +2,11 @@
> Cross-project heuristic adjustments based on observed variance data.
>
> **Note:** This file contains generic patterns only. Project-specific evidence is stored in each project's `docs/orchestrator-learnings.json`.
> **Note:** This file contains generic patterns only. Project-specific evidence is stored in each project's `docs/tasks/orchestrator-learnings.json`.
## Task Type Multipliers
Apply these multipliers to base estimates from `orchestrator.md`:
Apply these multipliers to base estimates from `ORCHESTRATOR.md`:
| Task Type | Base Estimate | Multiplier | Confidence | Samples | Last Updated |
|-----------|---------------|------------|------------|---------|--------------|
@@ -37,7 +37,7 @@ Apply to all estimates based on task position in milestone:
Final Estimate = Base Estimate × Type Multiplier × Phase Factor × TDD Overhead
Where:
- Base Estimate: From orchestrator.md task type table
- Base Estimate: From ORCHESTRATOR.md task type table
- Type Multiplier: From table above (default 1.0)
- Phase Factor: 1.45 / 1.25 / 1.10 based on position
- TDD Overhead: 1.20 if tests required
@@ -122,5 +122,5 @@ Where:
## Where to Find Project-Specific Data
- **Project learnings:** `<project>/docs/orchestrator-learnings.json`
- **Project learnings:** `<project>/docs/tasks/orchestrator-learnings.json`
- **Cross-project metrics:** `jarvis-brain/data/orchestrator-metrics.json`

63
guides/PRD.md Normal file
View File

@@ -0,0 +1,63 @@
# PRD Requirement Guide (MANDATORY)
This guide defines how requirements are captured before coding.
## Hard Rules
1. Before coding begins, `docs/PRD.md` or `docs/PRD.json` MUST exist.
2. The PRD is the authoritative requirements source for implementation and testing.
3. The main agent MUST prepare or update the PRD using user input and available project context before implementation starts.
4. The agent MUST NOT invent requirements silently.
5. In steered autonomy mode, best-guess decisions are REQUIRED when needed; each guessed decision MUST be marked with `ASSUMPTION:` and rationale.
## PRD Format
Allowed canonical formats:
1. `docs/PRD.md`
2. `docs/PRD.json`
Either format is valid. Both may exist if one is a transformed representation of the other.
For markdown PRDs, start from `~/.config/mosaic/templates/docs/PRD.md.template`.
## Best-Guess Mode
Steered autonomy is the default operating mode.
1. Agent SHOULD fill missing decisions in the PRD without waiting for routine confirmation.
2. Agent MUST mark each guessed decision with `ASSUMPTION:` and rationale.
3. If user explicitly requests strict-confirmation mode, the agent MUST ask before unresolved decisions are finalized.
4. For high-impact security/compliance/release uncertainty, escalate only if the decision cannot be safely constrained with rollback-ready defaults.
## Minimum PRD Content
Every PRD MUST include:
1. Problem statement and objective
2. In-scope and out-of-scope
3. User/stakeholder requirements
4. Functional requirements
5. Non-functional requirements (security, performance, reliability, observability)
6. Acceptance criteria
7. Constraints and dependencies
8. Risks and open questions
9. Testing and verification expectations
10. Delivery/milestone intent
## Pre-Coding Gate
Coding MUST NOT begin until:
1. PRD file exists (`docs/PRD.md` or `docs/PRD.json`)
2. PRD has required sections
3. Unresolved decisions are captured as explicit `ASSUMPTION:` entries with rationale and planned validation
## Change Control
When requirements materially change:
1. Update PRD first.
2. Then update implementation plan/tasks.
3. Then implement code changes.
Implementation that diverges from PRD without PRD updates is a blocker.

114
guides/QA-TESTING.md Normal file
View File

@@ -0,0 +1,114 @@
# QA & Testing Guide
## Before Starting
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review `docs/PRD.md` or `docs/PRD.json` as the requirements source.
4. Review acceptance criteria and affected change surfaces.
## Testing Policy (Hard Rules)
1. Situational testing is the PRIMARY validation gate.
2. Baseline testing is REQUIRED for all software changes.
3. TDD is risk-based and REQUIRED only for defined high-risk change types.
4. Tests MUST validate requirements and behavior, not only internal implementation details.
## Priority Order
1. Situational tests: prove requirements and real behavior on changed surfaces.
2. Baseline tests: lint/type/unit/integration safety checks.
3. TDD discipline: applied where risk justifies test-first workflow.
## Risk-Based TDD Requirement
| Change Type | TDD Requirement | Required Action |
|---|---|---|
| Bug fix | REQUIRED | Write a failing reproducer test first, then fix. |
| Security/auth/permission logic | REQUIRED | Write failing security/permission-path test first. |
| Critical business logic or data mutation rules | REQUIRED | Write failing rule/invariant test first. |
| API behavior regression | REQUIRED | Write failing contract/behavior test first. |
| Low-risk UI copy/style/layout | OPTIONAL | Add verification tests as appropriate; TDD recommended, not mandatory. |
| Mechanical refactor with unchanged behavior | OPTIONAL | Ensure regression/smoke coverage and situational evidence. |
If TDD is not required and skipped, record rationale in scratchpad.
If TDD is required and skipped, task is NOT complete.
## Baseline Test Requirements
For all software changes, run baseline checks applicable to the repo:
1. lint/static checks
2. type checks
3. unit tests for changed logic
4. integration tests for changed boundaries
## Situational Testing Matrix (Primary Gate)
| Change Surface | Required Situational Tests |
|---|---|
| Authentication/authorization | auth failure-path tests, permission boundary tests, token/session validation |
| Database schema/migrations | migration up/down validation, rollback safety, data integrity checks |
| API contract changes | backward compatibility checks, consumer-impact tests, contract tests |
| Frontend/UI workflow changes | end-to-end flow tests, accessibility sanity checks, state transition checks |
| CI/CD or deployment changes | pipeline execution validation, artifact integrity checks, rollback path check |
| Security-sensitive logic | abuse-case tests, input validation fuzzing/sanitization checks |
| Performance-critical path | baseline comparison, regression threshold checks |
## Coverage Requirements
### Minimum Standards
- Overall Coverage: 85% minimum
- Critical Paths: 95% minimum (auth, payments, data mutations)
- New Code: 90% minimum
Coverage is necessary but NOT sufficient. Passing coverage does not replace situational verification.
## Requirements-to-Evidence Mapping (Mandatory)
Before completion, map each acceptance criterion to concrete evidence.
Acceptance criteria MUST come from the active PRD.
Template:
```markdown
| Acceptance Criterion | Verification Method | Evidence |
|---|---|---|
| AC-1: ... | Situational test / baseline test / manual verification | command + result |
| AC-2: ... | ... | ... |
```
## Test Quality Rules
1. Test behavior and outcomes, not private implementation details.
2. Include failure-path and edge-case assertions for changed behavior.
3. Keep tests deterministic; no new flaky tests.
4. Keep tests isolated; no dependency on execution order.
## Anti-Gaming Rules
1. Do NOT stop at "tests pass" if acceptance criteria are not verified.
2. Do NOT write narrow tests that only satisfy assertions while missing real workflow behavior.
3. Do NOT claim completion without situational evidence for impacted surfaces.
## Reporting
QA report MUST include:
1. baseline tests run and outcomes
2. situational tests run and outcomes
3. TDD usage decision (required/applied or optional/skipped with rationale)
4. acceptance-criteria-to-evidence mapping
5. coverage results
6. residual risk notes
## Before Completing
1. Baseline tests pass.
2. Required situational tests pass.
3. TDD obligations met for required change types.
4. Acceptance criteria mapped to evidence.
5. No flaky tests introduced.
6. CI pipeline passes (if available).
7. Scratchpad updated with results.

38
guides/typescript.md → guides/TYPESCRIPT.md
View File

@@ -11,6 +11,44 @@ Based on Google TypeScript Style Guide with stricter enforcement.
1. **Explicit over implicit** — Always declare types, never rely on inference for public APIs
2. **Specific over generic** — Use the narrowest type that works
3. **Safe over convenient** — Type safety is not negotiable
4. **Contract-first boundaries** — Cross-module and API payloads MUST use dedicated DTO files
---
## DTO Contract (MANDATORY)
DTO files are REQUIRED for TypeScript module boundaries to preserve shared context and consistency.
Hard requirements:
1. Input and output payloads crossing module boundaries MUST be defined in `*.dto.ts` files.
2. Controller/service boundary payloads MUST use DTO types; inline object literal types are NOT allowed.
3. Public API request/response contracts MUST use DTO files and remain stable across modules.
4. Shared DTOs used by multiple modules MUST live in a shared location (for example `src/shared/dto/` or `packages/shared/dto/`).
5. ORM/entity models MUST NOT be exposed directly across module boundaries; map them to DTOs.
6. DTO changes MUST be reflected in tests and documentation when contracts change.
```typescript
// ❌ WRONG: inline payload contract at boundary
export function createUser(payload: { email: string; role: string }): Promise<User> { }
// ✅ CORRECT: dedicated DTO file contract
// user-create.dto.ts
export interface UserCreateDto {
email: string;
role: UserRole;
}
// user-response.dto.ts
export interface UserResponseDto {
id: string;
email: string;
role: UserRole;
}
// service.ts
export function createUser(payload: UserCreateDto): Promise<UserResponseDto> { }
```
---

0
guides/vault-secrets.md → guides/VAULT-SECRETS.md
View File

338
guides/bootstrap.md
View File

@@ -1,338 +0,0 @@
# Project Bootstrap Guide
> Load this guide when setting up a new project for AI-assisted development.
## Overview
This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.) can work on it effectively. Proper bootstrapping ensures:
1. Agents understand the project structure and conventions
2. Orchestration works correctly with quality gates
3. Independent code review and security review are configured
4. Issue tracking is consistent across projects
## Quick Start
```bash
# Automated bootstrap (recommended)
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "my-project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo"
# Or manually using templates
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export TASK_PREFIX="MP"
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
```
---
## Step 1: Detect Project Type
Check what files exist in the project root to determine the type:
| File Present | Project Type | Template |
|---|---|---|
| `package.json` + `pnpm-workspace.yaml` + NestJS+Next.js | NestJS + Next.js Monorepo | `projects/nestjs-nextjs/` |
| `pyproject.toml` + `manage.py` | Django | `projects/django/` |
| `pyproject.toml` (no Django) | Python (generic) | Generic template |
| `package.json` (no monorepo) | Node.js (generic) | Generic template |
| Other | Generic | Generic template |
```bash
# Auto-detect project type
detect_project_type() {
if [[ -f "pnpm-workspace.yaml" ]] && [[ -f "turbo.json" ]]; then
# Check for NestJS + Next.js
if grep -q "nestjs" package.json 2>/dev/null && grep -q "next" package.json 2>/dev/null; then
echo "nestjs-nextjs"
return
fi
fi
if [[ -f "manage.py" ]] && [[ -f "pyproject.toml" ]]; then
echo "django"
return
fi
if [[ -f "pyproject.toml" ]]; then
echo "python"
return
fi
if [[ -f "package.json" ]]; then
echo "nodejs"
return
fi
echo "generic"
}
```
---
## Step 2: Create CLAUDE.md
The `CLAUDE.md` file is the primary configuration file for AI agents. It tells them everything they need to know about the project.
### Using a Tech-Stack Template
```bash
# Set variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="Multi-tenant SaaS platform"
export PROJECT_DIR="my-project"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export TASK_PREFIX="MP"
# Use tech-stack-specific template if available
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
else
envsubst < "$HOME/.config/mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
fi
```
### Using the Generic Template
```bash
# Set all required variables
export PROJECT_NAME="My Project"
export PROJECT_DESCRIPTION="What this project does"
export REPO_URL="https://git.mosaicstack.dev/owner/repo"
export PROJECT_DIR="my-project"
export SOURCE_DIR="src"
export CONFIG_FILES="pyproject.toml / package.json"
export FRONTEND_STACK="N/A"
export BACKEND_STACK="Python / FastAPI"
export DATABASE_STACK="PostgreSQL"
export TESTING_STACK="pytest"
export DEPLOYMENT_STACK="Docker"
export BUILD_COMMAND="pip install -e ."
export TEST_COMMAND="pytest tests/"
export LINT_COMMAND="ruff check ."
export TYPECHECK_COMMAND="mypy ."
export QUALITY_GATES="ruff check . && mypy . && pytest tests/"
envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
```
### Required Sections
Every CLAUDE.md should contain:
1. **Project description** — One-line summary
2. **Conditional documentation loading** — Table of guides
3. **Technology stack** — What's used
4. **Repository structure** — Directory tree
5. **Development workflow** — Branch strategy, build, test
6. **Quality gates** — Commands that must pass
7. **Issue tracking** — Commit format, labels
8. **Code review** — Codex and fallback review commands
9. **Secrets management** — How secrets are handled
---
## Step 3: Create AGENTS.md
The `AGENTS.md` file contains agent-specific patterns, gotchas, and orchestrator integration details.
```bash
TYPE=$(detect_project_type)
TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
if [[ -d "$TEMPLATE_DIR" ]]; then
envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
else
envsubst < "$HOME/.config/mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
fi
```
### Living Document
AGENTS.md is a **living document**. Agents should update it when they discover:
- Reusable patterns (how similar features are built)
- Non-obvious requirements (e.g., "frontend env vars need NEXT_PUBLIC_ prefix")
- Common gotchas (e.g., "run migrations after schema changes")
- Testing approaches specific to this project
---
## Step 4: Create Directory Structure
```bash
# Create standard directories
mkdir -p docs/scratchpads
mkdir -p docs/templates
mkdir -p docs/reports
```
---
## Step 5: Initialize Repository Labels & Milestones
```bash
# Use the init script
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
# Or manually create standard labels
~/.config/mosaic/rails/git/issue-create.sh # (labels are created on first use)
```
### Standard Labels
| Label | Color | Purpose |
|-------|-------|---------|
| `epic` | `#3E4B9E` | Large feature spanning multiple issues |
| `feature` | `#0E8A16` | New functionality |
| `bug` | `#D73A4A` | Defect fix |
| `task` | `#0075CA` | General work item |
| `documentation` | `#0075CA` | Documentation updates |
| `security` | `#B60205` | Security-related |
| `breaking` | `#D93F0B` | Breaking change |
### Initial Milestone
Create the first milestone for MVP:
```bash
~/.config/mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
```
---
## Step 6: Set Up CI/CD Review Pipeline
### Woodpecker CI
```bash
# Copy Codex review pipeline
mkdir -p .woodpecker/schemas
cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
cp ~/.config/mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
# Add codex_api_key secret to Woodpecker CI dashboard
```
### GitHub Actions
For GitHub repos, use the official Codex GitHub Action instead:
```yaml
# .github/workflows/codex-review.yml
uses: openai/codex-action@v1
```
---
## Step 7: Verify Bootstrap
After bootstrapping, verify everything works:
```bash
# Check files exist
ls CLAUDE.md AGENTS.md docs/scratchpads/
# Verify CLAUDE.md has required sections
grep -c "Quality Gates" CLAUDE.md
grep -c "Technology Stack" CLAUDE.md
grep -c "Code Review" CLAUDE.md
# Verify quality gates run
eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
# Test Codex review (if configured)
~/.config/mosaic/rails/codex/codex-code-review.sh --help
```
---
## Available Templates
### Generic Templates
| Template | Path | Purpose |
|----------|------|---------|
| `CLAUDE.md.template` | `~/.config/mosaic/templates/agent/` | Generic project CLAUDE.md |
| `AGENTS.md.template` | `~/.config/mosaic/templates/agent/` | Generic agent context |
### Tech-Stack Templates
| Stack | Path | Includes |
|-------|------|----------|
| NestJS + Next.js | `~/.config/mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
| Django | `~/.config/mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |
### Orchestrator Templates
| Template | Path | Purpose |
|----------|------|---------|
| `tasks.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Task tracking |
| `orchestrator-learnings.json.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Variance tracking |
| `phase-issue-body.md.template` | `~/src/jarvis-brain/docs/templates/orchestrator/` | Gitea issue body |
| `scratchpad.md.template` | `~/src/jarvis-brain/docs/templates/` | Per-task working doc |
### Variables Reference
| Variable | Description | Example |
|----------|-------------|---------|
| `${PROJECT_NAME}` | Human-readable project name | "Mosaic Stack" |
| `${PROJECT_DESCRIPTION}` | One-line description | "Multi-tenant platform" |
| `${PROJECT_DIR}` | Directory name | "mosaic-stack" |
| `${PROJECT_SLUG}` | Python package slug | "mosaic_stack" |
| `${REPO_URL}` | Git remote URL | "https://git.mosaicstack.dev/mosaic/stack" |
| `${TASK_PREFIX}` | Orchestrator task prefix | "MS" |
| `${SOURCE_DIR}` | Source code directory | "src" or "apps" |
| `${QUALITY_GATES}` | Quality gate commands | "pnpm typecheck && pnpm lint && pnpm test" |
| `${BUILD_COMMAND}` | Build command | "pnpm build" |
| `${TEST_COMMAND}` | Test command | "pnpm test" |
| `${LINT_COMMAND}` | Lint command | "pnpm lint" |
| `${TYPECHECK_COMMAND}` | Type check command | "pnpm typecheck" |
| `${FRONTEND_STACK}` | Frontend technologies | "Next.js + React" |
| `${BACKEND_STACK}` | Backend technologies | "NestJS + Prisma" |
| `${DATABASE_STACK}` | Database technologies | "PostgreSQL" |
| `${TESTING_STACK}` | Testing technologies | "Vitest + Playwright" |
| `${DEPLOYMENT_STACK}` | Deployment technologies | "Docker" |
| `${CONFIG_FILES}` | Key config files | "package.json, tsconfig.json" |
---
## Bootstrap Scripts
### init-project.sh
Full project bootstrap with interactive and flag-based modes:
```bash
~/.config/mosaic/rails/bootstrap/init-project.sh \
--name "My Project" \
--type "nestjs-nextjs" \
--repo "https://git.mosaicstack.dev/owner/repo" \
--prefix "MP" \
--description "Multi-tenant platform"
```
### init-repo-labels.sh
Initialize standard labels and MVP milestone:
```bash
~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
```
---
## Checklist
After bootstrapping, verify:
- [ ] `CLAUDE.md` exists with all required sections
- [ ] `AGENTS.md` exists with patterns and quality gates
- [ ] `docs/scratchpads/` directory exists
- [ ] Git labels created (epic, feature, bug, task, etc.)
- [ ] Initial milestone created (0.1.0 MVP)
- [ ] Quality gates run successfully
- [ ] `.env.example` exists (if project uses env vars)
- [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
- [ ] Codex review scripts accessible (`~/.config/mosaic/rails/codex/`)

253
guides/ci-cd-pipelines.md
View File

@@ -12,7 +12,7 @@ GIT PUSH
QUALITY GATES (lint, typecheck, test, audit)
↓ all pass
BUILD (compile all packages)
↓ only on main/develop/tags
↓ only on main/tags
DOCKER BUILD & PUSH (Kaniko → Gitea Container Registry)
↓ all images pushed
PACKAGE LINKING (associate images with repository in Gitea)
@@ -123,10 +123,10 @@ when:
# Top-level: run quality gates on everything
- event: [push, pull_request, manual]
# Per-step: only build Docker images on main/develop/tags
# Per-step: only build Docker images on main/tags
docker-build-api:
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
```
@@ -150,24 +150,29 @@ docker-build-SERVICE:
from_secret: gitea_username
GITEA_TOKEN:
from_secret: gitea_token
RELEASE_BASE_VERSION: ${RELEASE_BASE_VERSION}
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
CI_PIPELINE_NUMBER: ${CI_PIPELINE_NUMBER}
commands:
- *kaniko_setup
- |
DESTINATIONS="--destination REGISTRY/ORG/IMAGE_NAME:${CI_COMMIT_SHA:0:8}"
SHORT_SHA="${CI_COMMIT_SHA:0:8}"
BUILD_ID="${CI_PIPELINE_NUMBER:-$SHORT_SHA}"
BASE_VERSION="${RELEASE_BASE_VERSION:?RELEASE_BASE_VERSION is required (example: 0.0.1)}"
DESTINATIONS="--destination REGISTRY/ORG/IMAGE_NAME:sha-$SHORT_SHA"
if [ "$CI_COMMIT_BRANCH" = "main" ]; then
DESTINATIONS="$DESTINATIONS --destination REGISTRY/ORG/IMAGE_NAME:latest"
elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
DESTINATIONS="$DESTINATIONS --destination REGISTRY/ORG/IMAGE_NAME:dev"
DESTINATIONS="$DESTINATIONS --destination REGISTRY/ORG/IMAGE_NAME:v${BASE_VERSION}-rc.${BUILD_ID}"
DESTINATIONS="$DESTINATIONS --destination REGISTRY/ORG/IMAGE_NAME:testing"
fi
if [ -n "$CI_COMMIT_TAG" ]; then
DESTINATIONS="$DESTINATIONS --destination REGISTRY/ORG/IMAGE_NAME:$CI_COMMIT_TAG"
fi
/kaniko/executor --context . --dockerfile PATH/TO/Dockerfile $DESTINATIONS
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
depends_on:
- build
@@ -184,15 +189,69 @@ docker-build-SERVICE:
### Image Tagging Strategy
Every build produces multiple tags:
Tagging MUST follow a two-layer model: immutable identity tags + mutable environment tags.
Immutable tags:
| Condition | Tag | Purpose |
|-----------|-----|---------|
| Always | `${CI_COMMIT_SHA:0:8}` | Immutable reference to exact commit |
| `main` branch | `latest` | Current production release |
| `develop` branch | `dev` | Current development build |
| Always | `sha-${CI_COMMIT_SHA:0:8}` | Immutable reference to exact commit |
| `main` branch | `v{BASE_VERSION}-rc.{BUILD_ID}` | Intermediate release candidate for the active milestone |
| Git tag (e.g., `v1.0.0`) | `v1.0.0` | Semantic version release |
Mutable environment tags:
| Tag | Purpose |
|-----|---------|
| `testing` | Current candidate under situational validation |
| `staging` (optional) | Pre-production validation target |
| `prod` | Current production pointer |
Hard rules:
- Do NOT use `latest` for deployment.
- Do NOT use `dev` as the primary deployment tag.
- Deployments MUST resolve to an immutable image digest.
### Digest-First Promotion (Hard Rule)
Deploy and promote by digest, not by mutable tag:
1. Build and push candidate tags (`sha-*`, `vX.Y.Z-rc.N`, `testing`).
2. Resolve the digest from `sha-*` tag.
3. Deploy that digest to testing and run situational tests.
4. If green, promote the same digest to `staging`/`prod` tags.
5. Create final semantic release tag (`vX.Y.Z`) only at milestone completion.
Example with `crane`:
```bash
DIGEST=$(crane digest REGISTRY/ORG/IMAGE:sha-${CI_COMMIT_SHA:0:8})
crane tag REGISTRY/ORG/IMAGE@${DIGEST} testing
# after situational tests pass:
crane tag REGISTRY/ORG/IMAGE@${DIGEST} prod
```
### Deployment Strategy: Blue-Green Default
- Blue-green is the default release strategy for lights-out operation.
- Canary is OPTIONAL and allowed only when automated SLO/error-rate monitoring and rollback triggers are configured.
- If canary guardrails are missing, you MUST use blue-green.
### Image Retention and Cleanup (Hard Rule)
Registry cleanup MUST be automated (daily or weekly job).
Retention policy:
- Keep all final release tags (`vX.Y.Z`) indefinitely.
- Keep digests currently referenced by `prod` and `testing` tags.
- Keep the most recent 20 RC tags (`vX.Y.Z-rc.N`) per service.
- Delete RC and `sha-*` tags older than 30 days when they are not referenced by active environments/releases.
Before deleting any image/tag:
- Verify digest is not currently deployed.
- Verify digest is not referenced by any active release/tag notes.
- Log cleanup actions in CI job output.
### Kaniko Options
Common flags for `/kaniko/executor`:
@@ -252,7 +311,10 @@ In `docker-compose.yml`:
```yaml
services:
api:
image: git.example.com/org/image:${IMAGE_TAG:-dev}
# Preferred: pin digest produced by CI and promoted by environment
image: git.example.com/org/image@${IMAGE_DIGEST}
# Optional channel pointer for non-prod:
# image: git.example.com/org/image:${IMAGE_TAG:-testing}
```
## Package Linking
@@ -315,7 +377,7 @@ link-packages:
link_package "image-name-1"
link_package "image-name-2"
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
depends_on:
- docker-build-image-1
@@ -350,6 +412,12 @@ Configure these in the Woodpecker UI (Settings > Secrets) or via CLI:
| `gitea_username` | Gitea username or service account | `push`, `manual`, `tag` |
| `gitea_token` | Gitea token with `package:write` scope | `push`, `manual`, `tag` |
### Required CI Variables (Non-Secret)
| Variable | Example | Purpose |
|----------|---------|---------|
| `RELEASE_BASE_VERSION` | `0.0.1` | Base milestone version used to generate RC tags (`v0.0.1-rc.N`) |
### Setting Secrets via CLI
```bash
@@ -554,9 +622,9 @@ security-trivy:
mkdir -p ~/.docker
echo "{\"auths\":{\"REGISTRY\":{\"username\":\"$$GITEA_USER\",\"password\":\"$$GITEA_TOKEN\"}}}" > ~/.docker/config.json
trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed \
REGISTRY/ORG/IMAGE:$${CI_COMMIT_SHA:0:8}
REGISTRY/ORG/IMAGE:sha-$${CI_COMMIT_SHA:0:8}
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
depends_on:
- docker-build-SERVICE
@@ -574,7 +642,7 @@ Docker build MUST depend on ALL quality + security steps. Trivy runs AFTER build
## Monorepo Considerations
### pnpm + Turbo (Mosaic Stack pattern)
### pnpm + Turbo
```yaml
variables:
@@ -589,7 +657,7 @@ steps:
- pnpm build # Turbo handles dependency order and caching
```
### npm Workspaces (U-Connect pattern)
### npm Workspaces
```yaml
variables:
@@ -684,24 +752,28 @@ steps:
from_secret: gitea_username
GITEA_TOKEN:
from_secret: gitea_token
RELEASE_BASE_VERSION: ${RELEASE_BASE_VERSION}
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
CI_PIPELINE_NUMBER: ${CI_PIPELINE_NUMBER}
commands:
- *kaniko_setup
- |
DESTINATIONS="--destination git.example.com/org/api:${CI_COMMIT_SHA:0:8}"
SHORT_SHA="${CI_COMMIT_SHA:0:8}"
BUILD_ID="${CI_PIPELINE_NUMBER:-$SHORT_SHA}"
BASE_VERSION="${RELEASE_BASE_VERSION:?RELEASE_BASE_VERSION is required}"
DESTINATIONS="--destination git.example.com/org/api:sha-$SHORT_SHA"
if [ "$CI_COMMIT_BRANCH" = "main" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/api:latest"
elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/api:dev"
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/api:v${BASE_VERSION}-rc.${BUILD_ID}"
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/api:testing"
fi
if [ -n "$CI_COMMIT_TAG" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/api:$CI_COMMIT_TAG"
fi
/kaniko/executor --context . --dockerfile src/api/Dockerfile $DESTINATIONS
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
depends_on: [build]
@@ -712,24 +784,28 @@ steps:
from_secret: gitea_username
GITEA_TOKEN:
from_secret: gitea_token
RELEASE_BASE_VERSION: ${RELEASE_BASE_VERSION}
CI_COMMIT_BRANCH: ${CI_COMMIT_BRANCH}
CI_COMMIT_TAG: ${CI_COMMIT_TAG}
CI_COMMIT_SHA: ${CI_COMMIT_SHA}
CI_PIPELINE_NUMBER: ${CI_PIPELINE_NUMBER}
commands:
- *kaniko_setup
- |
DESTINATIONS="--destination git.example.com/org/web:${CI_COMMIT_SHA:0:8}"
SHORT_SHA="${CI_COMMIT_SHA:0:8}"
BUILD_ID="${CI_PIPELINE_NUMBER:-$SHORT_SHA}"
BASE_VERSION="${RELEASE_BASE_VERSION:?RELEASE_BASE_VERSION is required}"
DESTINATIONS="--destination git.example.com/org/web:sha-$SHORT_SHA"
if [ "$CI_COMMIT_BRANCH" = "main" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/web:latest"
elif [ "$CI_COMMIT_BRANCH" = "develop" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/web:dev"
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/web:v${BASE_VERSION}-rc.${BUILD_ID}"
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/web:testing"
fi
if [ -n "$CI_COMMIT_TAG" ]; then
DESTINATIONS="$DESTINATIONS --destination git.example.com/org/web:$CI_COMMIT_TAG"
fi
/kaniko/executor --context . --dockerfile src/web/Dockerfile $DESTINATIONS
when:
- branch: [main, develop]
- branch: [main]
event: [push, manual, tag]
depends_on: [build]
@@ -763,8 +839,8 @@ steps:
}
link_package "api"
link_package "web"
when:
- branch: [main, develop]
when:
- branch: [main]
event: [push, manual, tag]
depends_on:
- docker-build-api
@@ -780,49 +856,130 @@ steps:
5. **Add package linking step** after all Docker builds
6. **Update `docker-compose.yml`** to reference registry images instead of local builds:
```yaml
image: git.example.com/org/service:${IMAGE_TAG:-dev}
image: git.example.com/org/service@${IMAGE_DIGEST}
```
7. **Test on develop branch first** — push a small change and verify the pipeline
7. **Test on a short-lived non-main branch first** — open a PR and verify quality gates before merging to `main`
8. **Verify images appear** in Gitea Packages tab after successful pipeline
## Post-Merge CI Monitoring (Hard Rule)
For source-code delivery, completion is not allowed at "PR opened" stage.
Required sequence:
1. Merge PR to `main` (squash) via Mosaic wrapper.
2. Monitor CI to terminal status:
```bash
~/.config/mosaic/rails/git/pr-ci-wait.sh -n <PR_NUMBER>
```
3. Require green status before claiming completion.
4. If CI fails, create remediation task(s) and continue until green.
5. If monitoring command fails, report blocker with the exact failed wrapper command and stop.
Woodpecker note:
- In Gitea + Woodpecker environments, commit status contexts generally reflect Woodpecker pipeline results.
- Always include CI run/status evidence in completion report.
## Queue Guard Before Push/Merge (Hard Rule)
Before pushing a branch or merging a PR, guard against overlapping project pipelines:
```bash
~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main
~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main
```
Behavior:
- If pipeline state is running/queued/pending, wait until queue clears.
- If timeout or API/auth failure occurs, treat as `blocked`, report exact failed wrapper command, and stop.
## Gitea as Unified Platform
Gitea provides **three services in one**, eliminating the need for separate Harbor and Verdaccio deployments:
Gitea provides **multiple services in one**, eliminating the need for separate registry platforms:
| Service | What Gitea Replaces | Registry URL |
|---------|---------------------|-------------|
| **Git hosting** | GitHub/GitLab | `https://GITEA_HOST/org/repo` |
| **Container registry** | Harbor, Docker Hub | `docker pull GITEA_HOST/org/image:tag` |
| **npm registry** | Verdaccio, Artifactory | `https://GITEA_HOST/api/packages/org/npm/` |
| **PyPI registry** | Private PyPI/Artifactory | `https://GITEA_HOST/api/packages/org/pypi` |
| **Maven registry** | Nexus, Artifactory | `https://GITEA_HOST/api/packages/org/maven` |
| **NuGet registry** | Azure Artifacts, Artifactory | `https://GITEA_HOST/api/packages/org/nuget/index.json` |
| **Cargo registry** | crates.io mirrors, Artifactory | `https://GITEA_HOST/api/packages/org/cargo` |
| **Composer registry** | Private Packagist, Artifactory | `https://GITEA_HOST/api/packages/org/composer` |
| **Conan registry** | Artifactory Conan | `https://GITEA_HOST/api/packages/org/conan` |
| **Conda registry** | Anaconda Server, Artifactory | `https://GITEA_HOST/api/packages/org/conda` |
| **Generic registry** | Generic binary stores | `https://GITEA_HOST/api/packages/org/generic` |
### Additional Package Types
Gitea also supports PyPI, Maven, NuGet, Cargo, Composer, Conan, Conda, Generic, and more. All use the same token authentication.
### Single Token, Three Services
### Single Token, Multiple Services
A Gitea token with `package:write` scope handles:
- `git push` / `git pull`
- `docker push` / `docker pull` (container registry)
- `npm publish` / `npm install` (npm registry)
- `twine upload` / `pip install` (PyPI registry)
- package operations for Maven/NuGet/Cargo/Composer/Conan/Conda/Generic registries
This means a single `gitea_token` secret in Woodpecker CI covers all CI/CD operations.
This means a single `gitea_token` secret in Woodpecker CI covers all CI/CD package operations.
## Python Packages on Gitea PyPI
For Python libraries and internal packages, use Gitea's built-in PyPI registry.
### Publish (Local or CI)
```bash
python -m pip install --upgrade build twine
python -m build
python -m twine upload \
--repository-url "https://GITEA_HOST/api/packages/ORG/pypi" \
--username "$GITEA_USERNAME" \
--password "$GITEA_TOKEN" \
dist/*
```
### Install (Consumer Projects)
```bash
pip install \
--extra-index-url "https://$GITEA_USERNAME:$GITEA_TOKEN@GITEA_HOST/api/packages/ORG/pypi/simple" \
your-package-name
```
### Woodpecker Step (Python Publish)
```yaml
publish-python-package:
image: python:3.12-slim
environment:
GITEA_USERNAME:
from_secret: gitea_username
GITEA_TOKEN:
from_secret: gitea_token
commands:
- python -m pip install --upgrade build twine
- python -m build
- python -m twine upload --repository-url https://GITEA_HOST/api/packages/ORG/pypi --username "$$GITEA_USERNAME" --password "$$GITEA_TOKEN" dist/*
when:
branch: [main]
event: [push]
```
### Architecture Simplification
**Before (3 services):**
**Before (4 services):**
```
Gitea (git) + Harbor (containers) + Verdaccio (npm)
↓ separate auth ↓ separate auth ↓ OAuth/Authentik
3 tokens 1 robot account 1 OIDC integration
3 backup targets complex RBAC group-based access
Gitea (git) + Harbor (containers) + Verdaccio (npm) + Private PyPI
↓ separate auth ↓ separate auth ↓ extra auth ↓ extra auth
multiple tokens robot/service users npm-specific token pip/twine token
fragmented access fragmented RBAC fragmented RBAC fragmented RBAC
```
**After (1 service):**
```
Gitea (git + containers + npm)
↓ single token
1 secret in Woodpecker
Gitea (git + containers + npm + pypi)
↓ unified secrets
1 credentials model in CI
1 backup target
unified RBAC via Gitea teams
```
@@ -900,5 +1057,5 @@ If a project currently uses Verdaccio (e.g., U-Connect at `npm.uscllc.net`), fol
- Link manually: Gitea UI > Packages > Select package > Link to repository
### Pipeline runs Docker builds on pull requests
- Verify `when` clause on Docker build steps restricts to `branch: [main, develop]`
- Verify `when` clause on Docker build steps restricts to `branch: [main]`
- Pull requests should only run quality gates, not build/push images

203
guides/e2e-delivery.md Normal file
View File

@@ -0,0 +1,203 @@
# E2E Delivery Procedure (MANDATORY)
This guide is REQUIRED for all agent sessions.
## 0. Mode Handshake (Before Any Action)
First response MUST declare mode before tool calls or implementation steps:
1. Orchestration mission: `Now initiating Orchestrator mode...`
2. Implementation mission: `Now initiating Delivery mode...`
3. Review-only mission: `Now initiating Review mode...`
## 1. PRD Gate (Before Coding)
1. Ensure `docs/PRD.md` or `docs/PRD.json` exists before coding.
2. Load `~/.config/mosaic/guides/PRD.md`.
3. Prepare/update PRD from user input and available project context.
4. If requirements are missing:
- proceed with best-guess assumptions by default,
- mark each assumption with `ASSUMPTION:` and rationale,
- escalate only when uncertainty is high-impact and cannot be bounded safely.
5. Treat PRD as the requirement source for implementation, testing, and review.
## 1a. Tracking Gate (Before Coding)
1. For non-trivial work, `docs/TASKS.md` MUST exist before coding.
2. If `docs/TASKS.md` is missing, create it from `~/.config/mosaic/templates/docs/TASKS.md.template`.
3. Detect provider first via `~/.config/mosaic/rails/git/detect-platform.sh`.
4. For issue/PR/milestone operations, use Mosaic wrappers first (`~/.config/mosaic/rails/git/*.sh`).
5. If external git provider is available (Gitea/GitHub/GitLab), create or update issue(s) before coding.
6. Record provider issue reference(s) in `docs/TASKS.md` (example: `#123`).
7. If no external provider is available, use internal task refs in `docs/TASKS.md` (example: `TASKS:T1`).
8. Scratchpad MUST reference both task ID and issue/internal ref.
## 2. Intake and Scope
1. Define scope, constraints, and acceptance criteria.
2. Identify affected surfaces (API, DB, UI, infra, auth, CI/CD, docs).
3. Identify required guides and load them before implementation.
4. For code/API/auth/infra changes, load `~/.config/mosaic/guides/DOCUMENTATION.md`.
5. Determine budget constraints:
- if the user provided a plan limit or token budget, treat it as a HARD cap,
- if budget is unknown, derive a working budget from estimates and runtime limits, then continue autonomously.
6. Record budget assumptions and caps in the scratchpad before implementation starts.
7. Track estimated vs used tokens per logical unit and adapt strategy to remain inside budget.
8. If projected usage exceeds budget, auto-reduce scope/parallelism first; escalate only if cap still cannot be met.
## 2a. Steered Autonomy (Lights-Out)
1. Agent owns delivery end-to-end: planning, coding, testing, review, PR/repo operations, release/tag, and deployment (when in scope).
2. Human intervention is escalation-only; do not pause for routine approvals or handoffs.
3. Continue execution until completion criteria are met or an escalation trigger is hit.
## 3. Scratchpad Requirement
1. Create a task-specific scratchpad before implementation.
2. Record:
- objective
- plan
- progress checkpoints
- tests run
- risks/blockers
- final verification evidence
## 4. Embedded Execution Cycle (MANDATORY)
For implementation work, you MUST run this cycle in order:
1. `plan` - map PRD requirements to concrete implementation steps.
2. `code` - implement one logical unit.
3. `test` - run required baseline and situational checks for that unit.
4. `review` - perform independent code review on the current delta.
5. `remediate` - fix all findings and any test failures.
6. `review` - re-review remediated changes until blockers are cleared.
7. `commit` - commit only when the logical unit passes tests and review.
8. `pre-push queue guard` - before pushing, wait for running/queued project pipelines to clear: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push`.
9. `push` - push immediately after queue guard passes.
10. `PR integration` - if external git provider is available, create/update PR to `main` and merge with required strategy via Mosaic wrappers.
11. `pre-merge queue guard` - before merging PR, wait for running/queued project pipelines to clear: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge`.
12. `CI/pipeline verification` - wait for terminal CI status and require green before completion (`~/.config/mosaic/rails/git/pr-ci-wait.sh` for PR-based workflow).
13. `issue closure` - close linked external issue (or close internal `docs/TASKS.md` task ref when provider is unavailable).
14. `greenfield situational test` - validate required user flows in a clean environment/startup path (post-merge for trunk workflow changes).
15. `deploy + post-deploy validation` - when deployment is in scope, deploy to configured target and run post-deploy health/smoke checks.
16. `repeat` - continue until all acceptance criteria are complete.
### Post-PR Hard Gate (Execute Sequentially, No Exceptions)
1. `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`
2. `~/.config/mosaic/rails/git/pr-merge.sh -n <PR_NUMBER> -m squash`
3. `~/.config/mosaic/rails/git/pr-ci-wait.sh -n <PR_NUMBER>`
4. `~/.config/mosaic/rails/git/issue-close.sh -i <ISSUE_NUMBER>` (or close internal `docs/TASKS.md` ref when no provider exists)
5. If any step fails: set status `blocked`, report the exact failed wrapper command, and stop.
6. Do not ask the human to perform routine merge/close operations.
7. Do not claim completion before step 4 succeeds.
### Forbidden Anti-Patterns
1. Do NOT stop at "PR created" or "PR updated".
2. Do NOT ask "should I merge?" for routine delivery PRs.
3. Do NOT ask "should I close the issue?" after merge + green CI.
If any step fails, you MUST remediate and re-run from the relevant step before proceeding.
If push-queue/merge-queue/PR merge/CI/issue closure fails, status is `blocked` (not complete) and you MUST report the exact failed wrapper command.
## 5. Testing Priority Model
Use this order of priority:
1. Situational tests are the PRIMARY gate and MUST prove changed behavior meets requirements.
2. Baseline tests are REQUIRED safety checks and MUST run for all software changes.
3. TDD is risk-based and REQUIRED only for specific high-risk change types.
## 6. Mandatory Test Baseline
For all software changes, you MUST run baseline checks applicable to the repo/toolchain:
1. lint (or equivalent static checks)
2. type checks (if language/tooling supports it)
3. unit tests for changed logic
4. integration tests for changed boundaries
## 7. Situational Testing Matrix (PRIMARY GATE)
Run additional tests based on what changed:
| Change Surface | Required Situational Tests |
|---|---|
| Authentication/authorization | auth failure-path tests, permission boundary tests, token/session validation |
| Database schema/migrations | migration up/down validation, rollback safety, data integrity checks |
| API contract changes | backward compatibility checks, consumer-impact tests, contract tests |
| Frontend/UI workflow changes | end-to-end flow tests, accessibility sanity checks, state transition checks |
| CI/CD or deployment changes | pipeline execution validation, artifact integrity checks, rollback path check |
| Security-sensitive logic | abuse-case tests, input validation fuzzing/sanitization checks |
| Performance-critical path | baseline comparison, regression threshold checks |
## 8. Risk-Based TDD Requirement
TDD is REQUIRED for:
1. bug fixes (write a reproducer test first)
2. security/auth/permission logic changes
3. critical business logic and data-mutation rules
TDD is RECOMMENDED (not mandatory) for low-risk UI, copy, styling, and mechanical refactors.
If TDD is skipped for a non-required case, record the rationale in the scratchpad.
## 9. Mandatory Code Review Gate
If you modify source code, you MUST run an independent code review before completion.
1. Use automated review tooling when available.
2. If automated tooling is unavailable, run manual review using `~/.config/mosaic/guides/CODE-REVIEW.md`.
3. Any blocker or critical finding MUST be fixed or tracked as an explicit remediation task before closure.
## 10. Mandatory Documentation Gate
For code/API/auth/infra changes, documentation updates are REQUIRED before completion.
1. Apply the standard in `~/.config/mosaic/guides/DOCUMENTATION.md`.
2. Update required docs in the same logical change set as implementation.
3. Complete `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`.
4. If publish platform is unspecified, ask the user to choose in-app or external platform before publishing.
5. Missing required documentation is a BLOCKER.
## 11. Completion Gate (All Required)
You MUST satisfy all items before completion:
1. Acceptance criteria met.
2. Baseline tests passed.
3. Situational tests passed (primary gate), including required greenfield situational validation.
4. PRD is current and implementation is aligned with PRD.
5. Acceptance criteria mapped to verification evidence.
6. Code review completed for source code changes.
7. Required documentation updates completed and reviewed.
8. Scratchpad updated with evidence.
9. Known risks documented.
10. No unresolved blocker hidden.
11. If deployment is in scope, deployment target, release version, and post-deploy verification evidence are documented.
12. `docs/TASKS.md` status and issue/internal references are updated to match delivered work.
13. If source code changed and external provider is available: PR merged to `main` (squash), with merge evidence recorded.
14. CI/pipeline status is terminal green for the merged PR/head commit.
15. Linked external issue is closed (or internal task ref is closed when no provider exists).
16. If any of items 13-15 fail due access/tooling, report `blocked` with exact failed wrapper command and do not claim completion.
## 12. Review and Reporting
Completion report MUST include:
1. what changed
2. PRD alignment summary
3. acceptance criteria to evidence mapping
4. what was tested (baseline + situational)
5. what was reviewed (code review scope)
6. what documentation was updated
7. command-level evidence summary
8. residual risks
9. deployment and post-deploy verification summary (if in scope)
10. explicit pass/fail status
11. tracking summary (`docs/TASKS.md` updates and issue/internal refs)
12. PR lifecycle summary (PR number, merge commit, merge method)
13. CI/pipeline summary (run/check URL, terminal status)
14. issue closure summary (issue number/ref and close evidence)

447
guides/orchestrator.md
View File

@@ -1,18 +1,47 @@
# Autonomous Orchestrator Guide
> Load this guide when orchestrating autonomous task completion across any project.
When spawning workers, include skill loading in the kickstart:
```bash
claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."codex exec "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
```
#### **MANDATORY**
- You MUST establish the requirements for a task, or series of tasks, before coding begins.
- You MUST ensure `docs/PRD.md` or `docs/PRD.json` exists before worker coding starts.
- You MUST use sequential-thinking to properly plan out tasks, milestones, epics, and PRD requirements prior to orchestrating agents.
- You MUST track tasks at the project level in docs/TASKS.md.
- You MUST keep the TASKS.md file updated with agent and tasks statuses.
- You MUST keep `docs/` root clean. Reports and working artifacts MUST be stored in scoped folders (`docs/reports/`, `docs/tasks/`, `docs/releases/`, `docs/scratchpads/`).
- You MUST enforce plan/token usage budgets when provided, and adapt orchestration strategy to remain within limits.
- You MUST enforce trunk workflow: workers branch from `main`, PR target is `main`, direct push to `main` is forbidden, and PR merges to `main` are squash-only.
- You MUST operate in steered-autonomy mode: human intervention is escalation-only; do not require the human to write code, review code, or manage PR/repo workflow.
- You MUST NOT declare task or issue completion until PR is merged, CI/pipeline is terminal green, and linked issue is closed (or internal TASKS ref is closed when provider is unavailable).
- Mosaic orchestration rules OVERRIDE runtime-default caution for routine push/merge/issue-close actions required by this workflow.
- Do NOT ask "should I merge?" or "should I close the issue?" for routine delivery flow after gates pass.
## Overview
The orchestrator **cold-starts** on any project with just a review report location and minimal kickstart. It autonomously:
1. Parses review reports to extract findings
2. Categorizes findings into phases by severity
3. Estimates token usage per task
4. Creates Gitea issues (phase-level)
5. Bootstraps `docs/tasks.md` from scratch
6. Coordinates completion using worker agents
## Session Start Handshake (Hard Rule)
**Key principle:** The orchestrator is the **sole writer** of `docs/tasks.md`. Worker agents execute tasks and report results — they never modify the tracking file.
Before any orchestration actions, the first response MUST be:
`Now initiating Orchestrator mode...`
Then proceed with orchestration bootstrap steps.
The orchestrator **cold-starts** on any project with just a review report location and minimal kickstart. It autonomously:
1. Prepares/updates project PRD (`docs/PRD.md` or `docs/PRD.json`) from user input and available project context
2. Parses review reports to extract findings
3. Categorizes findings into phases by severity
4. Estimates token usage per task
5. Creates phase issues in the configured git provider (Gitea/GitHub/GitLab)
6. Bootstraps `docs/TASKS.md` from scratch
7. Coordinates completion using worker agents
8. Enforces documentation completion gates for code/API/auth/infra changes
**Key principle:** The orchestrator is the **sole writer** of `docs/TASKS.md`. Worker agents execute tasks and report results — they never modify the tracking file.
---
@@ -25,8 +54,8 @@ The orchestrator **cold-starts** on any project with just a review report locati
- "Quickly fixes" something to save time — this is how drift starts
**The orchestrator ONLY:**
- Reads/writes `docs/tasks.md`
- Reads/writes `docs/orchestrator-learnings.json`
- Reads/writes `docs/TASKS.md`
- Reads/writes `docs/tasks/orchestrator-learnings.json`
- Delegates ALL code changes to workers (native subagent tool when available, otherwise Mosaic matrix rail)
- Parses worker JSON results
- Commits task tracking updates (tasks.md, learnings)
@@ -56,7 +85,7 @@ Matrix rail mode commands:
~/.config/mosaic/bin/mosaic-orchestrator-drain
```
In Matrix rail mode, keep `docs/tasks.md` as canonical project tracking and use
In Matrix rail mode, keep `docs/TASKS.md` as canonical project tracking and use
`.mosaic/orchestrator/` for deterministic worker dispatch state.
---
@@ -68,7 +97,7 @@ Use templates from `jarvis-brain/docs/templates/` to scaffold tracking files:
```bash
# Set environment variables
export PROJECT="project-name"
export MILESTONE="M1-Feature"
export MILESTONE="0.0.1"
export CURRENT_DATETIME=$(date -Iseconds)
export TASK_PREFIX="PR-SEC"
export PHASE_ISSUE="#1"
@@ -77,23 +106,41 @@ export PHASE_BRANCH="fix/security"
# Copy templates
TEMPLATES=~/src/jarvis-brain/docs/templates
# Create tasks.md (then populate with findings)
envsubst < $TEMPLATES/orchestrator/tasks.md.template > docs/tasks.md
# Create PRD if missing (before coding begins)
[[ -f docs/PRD.md || -f docs/PRD.json ]] || cp ~/.config/mosaic/templates/docs/PRD.md.template docs/PRD.md
# Create TASKS.md (then populate with findings)
envsubst < $TEMPLATES/orchestrator/tasks.md.template > docs/TASKS.md
# Create learnings tracking
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/orchestrator-learnings.json
mkdir -p docs/tasks docs/reports/deferred
envsubst < $TEMPLATES/orchestrator/orchestrator-learnings.json.template > docs/tasks/orchestrator-learnings.json
# Create review report structure (if doing new review)
$TEMPLATES/reports/review-report-scaffold.sh codebase-review
```
Milestone versioning (HARD RULE):
- Pre-MVP milestones MUST start at `0.0.1`.
- Pre-MVP progression MUST remain in `0.0.x` (`0.0.2`, `0.0.3`, ...).
- `0.1.0` is reserved for MVP release.
- You MUST NOT start pre-MVP planning at `0.1.0`.
Branch and merge strategy (HARD RULE):
- Workers use short-lived task branches from `origin/main`.
- Worker task branches merge back via PR to `main` only.
- Direct pushes to `main` are prohibited.
- PR merges to `main` MUST use squash merge.
**Available templates:**
| Template | Purpose |
|----------|---------|
| `orchestrator/tasks.md.template` | Task tracking table with schema |
| `orchestrator/orchestrator-learnings.json.template` | Variance tracking |
| `orchestrator/phase-issue-body.md.template` | Gitea issue body |
| `orchestrator/phase-issue-body.md.template` | Git provider issue body |
| `orchestrator/compaction-summary.md.template` | 60% checkpoint format |
| `reports/review-report-scaffold.sh` | Creates report directory |
| `scratchpad.md.template` | Per-task working document |
@@ -104,6 +151,16 @@ See `jarvis-brain/docs/templates/README.md` for full documentation.
## Phase 1: Bootstrap
### Step 0: Prepare PRD (Required Before Coding)
Before creating tasks or spawning workers:
1. Ensure `docs/PRD.md` or `docs/PRD.json` exists.
2. Build/update PRD from user input and available project context.
3. If requirements are missing, proceed with best-guess assumptions by default and mark each guessed requirement with `ASSUMPTION:` in PRD.
4. Escalate only when uncertainty is high-impact and cannot be safely bounded with rollback-ready defaults.
5. Do NOT start worker coding tasks until this step is complete.
### Step 1: Parse Review Reports
Review reports typically follow this structure:
@@ -169,6 +226,24 @@ Use these heuristics based on task type:
- Test requirements (+5-10K if tests needed)
- Documentation needs (+2-3K if docs needed)
### Step 3b: Budget Guardrail (HARD RULE)
Before creating dependencies or dispatching workers:
1. Determine budget cap:
- Use explicit user plan/token cap if provided.
- If no cap is provided, derive a soft cap from estimates and runtime constraints, then continue autonomously.
2. Calculate projected total from `estimate` column and record cap in task notes/scratchpad.
3. Apply dispatch mode by budget pressure:
- `<70%` of cap projected: normal orchestration (up to 2 workers).
- `70-90%` of cap projected: conservative mode (1 worker, tighter scope, no exploratory tasks).
- `>90%` of cap projected: freeze new worker starts; triage remaining work with user.
4. If projected usage exceeds cap, first reduce scope/parallelism automatically.
If cap still cannot be met, STOP and ask user to:
- reduce scope, or
- split into phases, or
- approve a higher budget.
### Step 4: Determine Dependencies
**Automatic dependency rules:**
@@ -183,9 +258,18 @@ Use these heuristics based on task type:
- `{PREFIX}-CQ-{LAST}`: Phase 3 verification
- `{PREFIX}-TEST-{LAST}`: Phase 4 verification (final quality gates)
### Step 5: Create Gitea Issues (Phase-Level)
### Step 5: Create Phase Issues (Gitea, GitHub, or GitLab)
Create ONE issue per phase using git scripts:
You MUST create ONE issue per phase in the configured external git provider.
Milestone binding rule:
- When the project is pre-MVP, issue milestones MUST use a `0.0.x` milestone.
- `0.1.0` MUST be used only for the MVP release milestone.
Provider options:
1. Gitea (preferred when available) via Mosaic helper:
```bash
~/.config/mosaic/rails/git/issue-create.sh \
@@ -201,6 +285,7 @@ Create ONE issue per phase using git scripts:
- [ ] All critical findings remediated
- [ ] Quality gates passing
- [ ] Required documentation updates complete
- [ ] No new regressions
EOF
)" \
@@ -208,18 +293,44 @@ EOF
-m "{milestone-name}"
```
**Capture issue numbers** — you'll link tasks to these.
2. GitHub (if repository uses GitHub):
### Step 6: Create docs/tasks.md
```bash
gh issue create \
--title "Phase 1: Critical Security Fixes" \
--body-file /tmp/phase-1-body.md \
--label "security,critical" \
--milestone "{milestone-name}"
```
3. GitLab (if repository uses GitLab):
```bash
glab issue create \
--title "Phase 1: Critical Security Fixes" \
--description-file /tmp/phase-1-body.md \
--label "security,critical" \
--milestone "{milestone-name}"
```
No external provider fallback (HARD RULE):
- If Gitea/GitHub/GitLab is unavailable, you MUST track phase-level milestones and issue equivalents directly in `docs/TASKS.md`.
- In this mode, the `issue` column MUST use internal refs (example: `TASKS:P1`, `TASKS:P2`).
- You MUST keep `docs/TASKS.md` as the complete system of record for tasks, milestones, and issue status.
**Capture issue references** — you'll link tasks to these.
### Step 6: Create docs/TASKS.md
Create the file with this exact schema:
```markdown
# Tasks
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {PREFIX}-SEC-001 | not-started | SEC-API-1: Brief description | #{N} | api | fix/security | | {PREFIX}-SEC-002 | | | | 8K | |
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {PREFIX}-SEC-001 | not-started | SEC-API-1: Brief description | #{N} | api | fix/security | | {PREFIX}-SEC-002 | | | | 8K | | |
```
**Column definitions:**
@@ -227,9 +338,9 @@ Create the file with this exact schema:
| Column | Format | Purpose |
|--------|--------|---------|
| `id` | `{PREFIX}-{CAT}-{NNN}` | Unique task ID (e.g., MS-SEC-001) |
| `status` | `not-started` \| `in-progress` \| `done` \| `failed` | Current state |
| `status` | `not-started` \| `in-progress` \| `done` \| `failed` \| `blocked` \| `needs-qa` | Current state |
| `description` | `{FindingID}: Brief summary` | What to fix |
| `issue` | `#NNN` | Gitea issue (phase-level, all tasks in phase share) |
| `issue` | `#NNN` or `TASKS:Pn` | Provider issue ref (phase-level) or internal TASKS milestone ref |
| `repo` | Workspace name | `api`, `web`, `orchestrator`, etc. |
| `branch` | Branch name | `fix/security`, `fix/code-quality`, etc. |
| `depends_on` | Comma-separated IDs | Must complete first |
@@ -239,6 +350,10 @@ Create the file with this exact schema:
| `completed_at` | ISO 8601 | When work finished |
| `estimate` | `5K`, `15K`, etc. | Predicted token usage |
| `used` | `4.2K`, `12.8K`, etc. | Actual usage (fill on completion) |
| `notes` | free text | Review results, PR/CI/issue closure evidence, blocker commands |
Status rule:
- `done` is allowed only after PR merge + green CI + issue/ref closure for source-code tasks.
**Category prefixes:**
- `SEC` — Security (Phase 1-2)
@@ -246,11 +361,21 @@ Create the file with this exact schema:
- `CQ` — Code quality (Phase 3)
- `TEST` — Test coverage (Phase 4)
- `PERF` — Performance (Phase 3)
- `DOC` — Documentation updates/gates
### Step 6b: Add Documentation Tasks (MANDATORY)
For each phase containing code/API/auth/infra work:
1. Add explicit documentation tasks in `docs/TASKS.md` (or include docs in phase verification tasks).
2. Require completion of `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`.
3. Ensure phase acceptance criteria includes documentation completion.
4. Do not mark phase complete until documentation tasks are done.
### Step 7: Commit Bootstrap
```bash
git add docs/tasks.md
git add docs/TASKS.md
git commit -m "chore(orchestrator): Bootstrap tasks.md from review report
Parsed {N} findings into {M} tasks across {P} phases.
@@ -264,34 +389,61 @@ git push
```
1. git pull --rebase
2. Read docs/tasks.md
2. Read docs/TASKS.md
3. Find next task: status=not-started AND all depends_on are done
4. If no task available:
- All done? → Report success, run final retrospective, STOP
- Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent={identifier}, started_at={now}
6. Delegate worker task:
6. Budget gate (before dispatch):
- Compute cumulative used + remaining estimate
- If projected total > budget cap: STOP and request user decision (reduce scope/phase/increase cap)
- If projected total is 70-90% of cap: run conservative mode (single worker)
7. Delegate worker task:
- native mode: spawn worker agent via runtime subagent/task primitive
- matrix mode: enqueue/consume task in `.mosaic/orchestrator/tasks.json` and run `mosaic-orchestrator-matrix-cycle`
7. Wait for worker completion
8. Parse worker result (JSON)
9. **Variance check**: Calculate (actual - estimate) / estimate × 100
8. Wait for worker completion
9. Parse worker result (JSON)
10. **Variance check**: Calculate (actual - estimate) / estimate × 100
- If |variance| > 50%: Capture learning (see Learning & Retrospective)
- If |variance| > 100%: Flag as CRITICAL — review task classification
10. **Post-Coding Review** (see Phase 2b below)
11. Update tasks.md: status=done/failed/needs-qa, completed_at={now}, used={actual}
12. **Cleanup reports**: Remove processed report files for completed task
11. **Post-Coding Review** (see Phase 2b below)
12. **Documentation Gate**: Verify required docs were updated per `~/.config/mosaic/guides/DOCUMENTATION.md`
and checklist completed (`~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`) when applicable.
13. **PR + CI + Issue Closure Gate** (HARD RULE for source-code tasks):
- Before merging, run queue guard:
`~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose merge -B main`
- Ensure PR exists for the task branch (create/update via wrappers if needed):
`~/.config/mosaic/rails/git/pr-create.sh ... -B main`
- Merge via wrapper:
`~/.config/mosaic/rails/git/pr-merge.sh -n {PR_NUMBER} -m squash`
- Wait for terminal CI status:
`~/.config/mosaic/rails/git/pr-ci-wait.sh -n {PR_NUMBER}`
- Close linked issue after merge + green CI:
`~/.config/mosaic/rails/git/issue-close.sh -i {ISSUE_NUMBER}`
- If any wrapper command fails, mark task `blocked`, record the exact failed wrapper command, report blocker, and STOP.
- Do NOT stop at "PR created" or "PR merged pending CI".
- Do NOT claim completion before CI is green and issue/internal ref is closed.
14. Update tasks.md: status=done/failed/needs-qa/blocked, completed_at={now}, used={actual}
15. Recalculate budget position:
- cumulative used
- projected remaining from estimates
- total projected at completion
16. **Cleanup reports**: Remove processed report files for completed task
```bash
# Find and remove reports matching the finding ID
find docs/reports/qa-automation/pending/ -name "*{finding_id}*" -delete 2>/dev/null || true
# If task failed, move reports to escalated/ instead
```
13. Commit + push: git add docs/tasks.md .gitignore && git commit && git push
14. If phase verification task: Run phase retrospective, clean up all phase reports
15. Check context usage
16. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
17. If < 55%: Go to step 1
18. After user runs /compact and says "continue": Go to step 1
17. Commit + push: git add docs/TASKS.md .gitignore && git commit && git push
18. If phase verification task: Run phase retrospective, clean up all phase reports
19. Check context usage
20. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
21. Check budget usage:
- If projected total > cap: STOP and request user decision before new tasks
- If projected total is 70-90% of cap: continue in conservative mode
22. If < 55% context and within budget: Go to step 1
23. After user runs /compact and says "continue": Go to step 1
```
---
@@ -375,7 +527,7 @@ Review the code changes on branch {branch} against {base_branch}.
- Security (OWASP Top 10, secrets, injection)
- Testing (coverage, quality)
- Code quality (complexity, duplication)
3. Reference: ~/.config/mosaic/guides/code-review.md
3. Reference: ~/.config/mosaic/guides/CODE-REVIEW.md
Report findings as JSON:
```json
@@ -432,26 +584,34 @@ Construct this from the task row and pass to worker via Task tool:
## Workflow
1. Checkout branch: `git checkout {branch} || git checkout -b {branch} develop && git pull`
2. Read the finding details from the report
3. Implement the fix following existing code patterns
4. Run quality gates (ALL must pass — zero lint errors, zero type errors, all tests green):
1. Checkout branch: `git fetch origin && (git checkout {branch} || git checkout -b {branch} origin/main) && git rebase origin/main`
2. Read `docs/PRD.md` or `docs/PRD.json` and align implementation with PRD requirements
3. Read the finding details from the report
4. Implement the fix following existing code patterns
5. Run quality gates (ALL must pass — zero lint errors, zero type errors, all tests green):
```bash
{quality_gates_command}
```
**MANDATORY:** This ALWAYS includes linting. If the project has a linter configured
(ESLint, Biome, ruff, etc.), you MUST run it and fix ALL violations in files you touched.
Do NOT leave lint warnings or errors for someone else to clean up.
5. If gates fail: Fix and retry. Do NOT report success with failures.
6. Commit: `git commit -m "fix({finding_id}): brief description"`
7. Push: `git push origin {branch}`
8. Report result as JSON (see format below)
6. Run REQUIRED situational tests based on changed surfaces (see `~/.config/mosaic/guides/E2E-DELIVERY.md` and `~/.config/mosaic/guides/QA-TESTING.md`).
7. If task is bug fix/security/auth/critical business logic, apply REQUIRED TDD discipline per `~/.config/mosaic/guides/QA-TESTING.md`.
8. If gates or required situational tests fail: Fix and retry. Do NOT report success with failures.
9. Commit: `git commit -m "fix({finding_id}): brief description"`
10. Before push, run queue guard: `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push -B main`
11. Push: `git push origin {branch}`
12. Report result as JSON (see format below)
## Git Scripts
For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
- `~/.config/mosaic/rails/git/issue-view.sh -i {N}`
- `~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
- `~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B main`
- `~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge -B main`
- `~/.config/mosaic/rails/git/pr-merge.sh -n {PR_NUMBER} -m squash`
- `~/.config/mosaic/rails/git/pr-ci-wait.sh -n {PR_NUMBER}`
- `~/.config/mosaic/rails/git/issue-close.sh -i {N}`
Standard git commands (pull, commit, push, checkout) are fine.
@@ -469,6 +629,9 @@ End your response with this JSON block:
}
```
`status=success` means "code pushed and ready for orchestrator integration gates";
it does NOT mean PR merged/CI green/issue closed.
## Post-Coding Review
After you complete and push your changes, the orchestrator will independently
@@ -478,7 +641,7 @@ created. You do NOT need to run the review yourself — the orchestrator handles
## Rules
- DO NOT modify docs/tasks.md
- DO NOT modify docs/TASKS.md
- DO NOT claim other tasks
- Complete this single task, report results, done
````
@@ -493,14 +656,14 @@ created. You do NOT need to run the review yourself — the orchestrator handles
- Compaction causes **protocol drift** — agent "remembers" gist but loses specifics
- Post-compaction agents may violate core rules (e.g., letting workers modify tasks.md)
- Fresh orchestrator has **100% protocol fidelity**
- All state lives in `docs/tasks.md` — the orchestrator is **stateless and replaceable**
- All state lives in `docs/TASKS.md` — the orchestrator is **stateless and replaceable**
**At threshold (55-60%):**
1. Complete current task
2. Persist all state:
- Update docs/tasks.md with all progress
- Update docs/orchestrator-learnings.json with variances
- Update docs/TASKS.md with all progress
- Update docs/tasks/orchestrator-learnings.json with variances
- Commit and push both files
3. Output **ORCHESTRATOR HANDOFF** message with ready-to-use takeover kickstart
4. **STOP COMPLETELY** — do not continue working
@@ -517,8 +680,8 @@ Progress: {completed}/{total} tasks ({percentage}%)
Current phase: Phase {N} ({phase_name})
State persisted:
- docs/tasks.md ✓
- docs/orchestrator-learnings.json ✓
- docs/TASKS.md ✓
- docs/tasks/orchestrator-learnings.json ✓
## Takeover Kickstart
@@ -531,8 +694,8 @@ Continue {mission_description} from existing state.
## Setup
- Project: {project_path}
- State: docs/tasks.md (already populated)
- Protocol: docs/claude/orchestrator.md
- State: docs/TASKS.md (already populated)
- Protocol: ~/.config/mosaic/guides/ORCHESTRATOR.md
- Quality gates: {quality_gates_command}
## Resume Point
@@ -541,11 +704,11 @@ Continue {mission_description} from existing state.
- Progress: {completed}/{total} tasks ({percentage}%)
## Instructions
1. Read docs/claude/orchestrator.md for protocol
2. Read docs/tasks.md to understand current state
1. Read ~/.config/mosaic/guides/ORCHESTRATOR.md for protocol
2. Read docs/TASKS.md to understand current state
3. Continue execution from task {task_id}
4. Follow Two-Phase Completion Protocol
5. You are the SOLE writer of docs/tasks.md
5. You are the SOLE writer of docs/TASKS.md
---
STOP: Terminate this session and spawn fresh orchestrator with the kickstart above.
@@ -583,7 +746,7 @@ Each major phase uses a two-phase approach to maximize completion while managing
| Architectural | Requires design change | Document and defer |
3. **Work priority:** Quick-win → Medium → Hard
4. **Document deferrals** in `docs/deferred-errors.md`:
4. **Document deferrals** in `docs/reports/deferred/deferred-errors.md`:
```markdown
## {PREFIX}-XXX: [Error description]
- File: path/to/file.ts:123
@@ -608,7 +771,7 @@ Do NOT proceed to the next major phase until the current phase reaches Polish co
✅ Phase 2 Polish: 118 errors triaged
- 40 medium → fixed
- 78 low → EACH documented with rationale
✅ Phase 2 Complete: Created docs/deferred-errors.md
✅ Phase 2 Complete: Created docs/reports/deferred/deferred-errors.md
→ NOW proceed to Phase 3
❌ WRONG: Phase 2 at 91%, "low priority acceptable", starting Phase 3
@@ -643,7 +806,7 @@ Orchestrators capture learnings to improve future estimation accuracy.
|----------|--------|
| 0-30% | Log only (acceptable) |
| 30-50% | Flag for review |
| 50-100% | Capture learning to `docs/orchestrator-learnings.json` |
| 50-100% | Capture learning to `docs/tasks/orchestrator-learnings.json` |
| >100% | CRITICAL — review task classification, possible mismatch |
### Task Type Classification
@@ -662,7 +825,7 @@ Classify tasks by description keywords for pattern analysis:
### Capture Learning
When |variance| > 50%, append to `docs/orchestrator-learnings.json`:
When |variance| > 50%, append to `docs/tasks/orchestrator-learnings.json`:
```json
{
@@ -708,7 +871,7 @@ Next: MS-SEC-004
### Cross-Project Learnings
Universal heuristics are maintained in `~/.config/mosaic/guides/orchestrator-learnings.md`.
Universal heuristics are maintained in `~/.config/mosaic/guides/ORCHESTRATOR-LEARNINGS.md`.
After completing a milestone, review variance patterns and propose updates to the universal guide.
---
@@ -736,7 +899,7 @@ docs/reports/qa-automation/
| Task success | Delete matching reports from `pending/` |
| Task failed | Move reports to `escalated/` for investigation |
| Phase verification | Clean up all `pending/` reports for that phase |
| Milestone complete | Archive or delete entire `escalated/` directory |
| Milestone complete | Complete release + tag workflow, then archive or delete `escalated/` directory |
**Cleanup commands:**
```bash
@@ -766,6 +929,11 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
2. Skip to next unblocked task if possible
3. If all remaining tasks blocked: Report blockers, STOP
**PR/CI/Issue wrapper failure:**
1. Record task status as `blocked` in `docs/TASKS.md`.
2. Record the exact failed wrapper command (full command line) in task notes and user report.
3. STOP orchestration for that task; do not mark complete and do not silently fall back to raw provider commands.
**Git push conflict:**
1. `git pull --rebase`
2. If auto-resolves: push again
@@ -776,54 +944,151 @@ mv docs/reports/qa-automation/pending/*failing-file* docs/reports/qa-automation/
## Stopping Criteria
**ONLY stop if:**
1. All tasks in docs/tasks.md are `done`
1. All tasks in docs/TASKS.md are `done`
2. Critical blocker preventing progress (document and alert)
3. Context usage >= 55% — output COMPACTION REQUIRED checkpoint and wait
4. Absolute context limit reached AND cannot compact further
5. PRD is current and reflects delivered requirements (`docs/PRD.md` or `docs/PRD.json`)
6. Required documentation checklist is complete for applicable changes
7. For milestone completion, release + git tag steps are complete
8. For source-code tasks with external provider, merged PR evidence exists
9. For source-code tasks with external provider, CI/pipeline is terminal green
10. For linked external issues, closure is complete (or internal TASKS ref closure if no provider)
**DO NOT stop to ask "should I continue?"** — the answer is always YES.
**DO stop at 55-60%** — output the compaction checkpoint and wait for user to run `/compact`.
---
## Sprint Completion Protocol
## Merge-to-Main Candidate Protocol (Container Deployments)
When all tasks in `docs/tasks.md` are `done` (or triaged as `deferred`), archive the sprint artifacts before stopping. This preserves them for post-mortems, variance calibration, and historical reference.
If deployment is in scope and container images are used, every merge to `main` MUST execute this protocol:
### Archive Steps
1. Build and push immutable candidate image tags:
- `sha-<shortsha>` (always)
- `v{base-version}-rc.{build}` (for `main` merges)
- `testing` mutable pointer to the same digest
2. Resolve and record the image digest for each service.
3. Deploy by digest to testing environment (never deploy by mutable tag alone).
4. Run full situational testing against images pulled from the registry.
5. If tests pass, promote the SAME digest (no rebuild) to environment pointers (`staging`/`prod` as applicable).
6. If tests fail, rollback to last known-good digest and create remediation tasks immediately.
1. **Create archive directory** (if it doesn't exist):
Hard rules:
- `latest` MUST NOT be used as a deployment reference.
- Final semantic release tags (`vX.Y.Z`) are milestone-level only.
- Intermediate checkpoints use RC image tags (`vX.Y.Z-rc.N`) and digest promotion.
---
## Milestone Completion Protocol (Release + Tag Required)
When all tasks in `docs/TASKS.md` are `done` (or triaged as `deferred`), you MUST complete release/tag operations before declaring the milestone complete.
### Required Completion Steps
1. **Prepare release metadata**:
- `milestone-name` (human-readable)
- `milestone-version` (semantic version, e.g., `0.0.3`, `0.1.0`)
- `tag` = `v{milestone-version}` (e.g., `v0.0.3`)
2. **Verify documentation gate**:
- Confirm required docs were updated per `~/.config/mosaic/guides/DOCUMENTATION.md`.
- Confirm checklist completion: `~/.config/mosaic/templates/docs/DOCUMENTATION-CHECKLIST.md`.
- If docs are incomplete, STOP and create remediation task(s) before release/tag.
3. **Create and push annotated git tag**:
```bash
mkdir -p docs/tasks/
git pull --rebase
git tag -a "v{milestone-version}" -m "Release v{milestone-version} - {milestone-name}"
git push origin "v{milestone-version}"
```
2. **Move tasks.md to archive:**
4. **Create repository release** (provider-specific):
Gitea:
```bash
mv docs/tasks.md docs/tasks/{milestone-name}-tasks.md
tea releases create \
--tag "v{milestone-version}" \
--title "v{milestone-version}" \
--note "Milestone {milestone-name} completed."
```
GitHub:
```bash
gh release create "v{milestone-version}" \
--title "v{milestone-version}" \
--notes "Milestone {milestone-name} completed."
```
GitLab:
```bash
glab release create "v{milestone-version}" \
--name "v{milestone-version}" \
--notes "Milestone {milestone-name} completed."
```
No external provider fallback:
- Create and push annotated tag as above.
- Create `docs/releases/v{milestone-version}.md` with release notes and include milestone completion summary.
5. **Close milestone in provider**:
- Gitea/GitHub:
```bash
~/.config/mosaic/rails/git/milestone-close.sh -t "{milestone-name}"
```
- GitLab: close milestone via provider workflow (CLI or web UI).
If provider tooling is unavailable, record milestone closure status in `docs/TASKS.md` notes.
6. **Archive sprint artifacts**:
```bash
mkdir -p docs/tasks/
mv docs/TASKS.md docs/tasks/{milestone-name}-tasks.md
mv docs/tasks/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
```
Example: `docs/tasks/M6-AgentOrchestration-Fixes-tasks.md`
3. **Move learnings to archive:**
7. **Commit archive + release references**:
```bash
mv docs/orchestrator-learnings.json docs/tasks/{milestone-name}-learnings.json
```
git add docs/tasks/ docs/releases/ 2>/dev/null || true
git rm docs/TASKS.md docs/tasks/orchestrator-learnings.json 2>/dev/null || true
git commit -m "chore(orchestrator): Complete {milestone-name} milestone release
4. **Commit the archive:**
```bash
git add docs/tasks/
git rm docs/tasks.md docs/orchestrator-learnings.json 2>/dev/null || true
git commit -m "chore(orchestrator): Archive {milestone-name} sprint artifacts
{completed}/{total} tasks completed, {deferred} deferred.
Archived to docs/tasks/ for post-mortem reference."
- Tagged: v{milestone-version}
- Release published
- Artifacts archived to docs/tasks/"
git push
```
5. **Run final retrospective** — review variance patterns and propose updates to estimation heuristics.
8. **Run final retrospective** — review variance patterns and propose updates to estimation heuristics.
### Deployment Protocol (When In Scope)
If the milestone includes deployment, orchestrator MUST complete deployment before final completion status:
1. Determine deployment target from PRD, project config, or environment:
- `Portainer`
- `Coolify`
- `Vercel`
- other configured SaaS provider
2. Trigger deployment using provider API/CLI/webhook.
3. Deployment method MUST be digest-first:
- Resolve digest from candidate image (`sha-*` or `vX.Y.Z-rc.N`),
- deploy that digest,
- promote tags (`testing`/`staging`/`prod`) only after validation.
4. Run post-deploy verification:
- health endpoint checks,
- critical smoke tests,
- release/version verification,
- digest verification (running digest equals promoted digest).
5. Default strategy is blue-green. Canary is allowed only if automated metrics, thresholds, and rollback triggers are configured.
6. If verification fails, execute rollback/redeploy-safe path and mark milestone `blocked` until stable.
7. Record deployment evidence in milestone release notes and `docs/TASKS.md` notes, including digest and promoted tags.
8. Ensure registry cleanup is scheduled/enforced (retain release tags + active digests, purge stale RC/sha tags).
### Recovery
If an orchestrator starts and `docs/tasks.md` does not exist, check `docs/tasks/` for the most recent archive:
If an orchestrator starts and `docs/TASKS.md` does not exist, check `docs/tasks/` for the most recent archive:
```bash
ls -t docs/tasks/*-tasks.md 2>/dev/null | head -1
@@ -832,7 +1097,7 @@ ls -t docs/tasks/*-tasks.md 2>/dev/null | head -1
If found, this may indicate another session archived the file. The orchestrator should:
1. Report what it found in `docs/tasks/`
2. Ask whether to resume from the archived file or bootstrap fresh
3. If resuming: copy the archive back to `docs/tasks.md` and continue
3. If resuming: copy the archive back to `docs/TASKS.md` and continue
### Retention Policy
@@ -860,7 +1125,7 @@ Remediate findings from the codebase review.
- Task prefix: {PREFIX} (e.g., MS, UC)
## Protocol
Read ~/.config/mosaic/guides/orchestrator.md for full instructions.
Read ~/.config/mosaic/guides/ORCHESTRATOR.md for full instructions.
## Start
Bootstrap from the review report, then execute until complete.

202
guides/qa-testing.md
View File

@@ -1,202 +0,0 @@
# QA & Testing Guide
## Before Starting
1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review existing test structure and patterns
## Test-Driven Development (TDD) Process
### The TDD Cycle
1. **Red**: Write a failing test first
2. **Green**: Write minimal code to pass
3. **Refactor**: Improve code while keeping tests green
### TDD Rules
- Never write production code without a failing test
- Write only enough test to fail
- Write only enough code to pass
- Refactor continuously
## Coverage Requirements
### Minimum Standards
- **Overall Coverage**: 85% minimum
- **Critical Paths**: 95% minimum (auth, payments, data mutations)
- **New Code**: 90% minimum
### What to Cover
- All public interfaces
- Error handling paths
- Edge cases and boundaries
- Integration points
### What NOT to Count
- Generated code
- Configuration files
- Third-party library wrappers (thin wrappers only)
## Test Categories
### Unit Tests
- Test single functions/methods in isolation
- Mock external dependencies
- Fast execution (< 100ms per test)
- No network, database, or filesystem access
```python
def test_calculate_discount_applies_percentage():
result = calculate_discount(100, 0.20)
assert result == 80
```
### Integration Tests
- Test multiple components together
- Use real databases (test containers)
- Test API contracts
- Slower execution acceptable
```python
def test_create_user_persists_to_database(db_session):
user = create_user(db_session, "test@example.com")
retrieved = get_user_by_email(db_session, "test@example.com")
assert retrieved.id == user.id
```
### End-to-End Tests
- Test complete user workflows
- Use real browser (Playwright, Cypress)
- Test critical paths only (expensive to maintain)
```javascript
test('user can complete checkout', async ({ page }) => {
await page.goto('/products');
await page.click('[data-testid="add-to-cart"]');
await page.click('[data-testid="checkout"]');
await page.fill('#email', 'test@example.com');
await page.click('[data-testid="submit-order"]');
await expect(page.locator('.order-confirmation')).toBeVisible();
});
```
## Test Structure
### Naming Convention
```
test_{what}_{condition}_{expected_result}
Examples:
- test_login_with_valid_credentials_returns_token
- test_login_with_invalid_password_returns_401
- test_get_user_when_not_found_returns_404
```
### Arrange-Act-Assert Pattern
```python
def test_add_item_to_cart_increases_count():
# Arrange
cart = Cart()
item = Item(id=1, name="Widget", price=9.99)
# Act
cart.add(item)
# Assert
assert cart.item_count == 1
assert cart.total == 9.99
```
### Test Isolation
- Each test should be independent
- Use setup/teardown for common state
- Clean up after tests
- Don't rely on test execution order
## Mocking Guidelines
### When to Mock
- External APIs and services
- Time-dependent operations
- Random number generation
- Expensive operations
### When NOT to Mock
- The code under test
- Simple data structures
- Database in integration tests
### Mock Example
```python
def test_send_notification_calls_email_service(mocker):
mock_email = mocker.patch('services.email.send')
send_notification(user_id=1, message="Hello")
mock_email.assert_called_once_with(
to="user@example.com",
subject="Notification",
body="Hello"
)
```
## Test Data Management
### Fixtures
- Use factories for complex objects
- Keep test data close to tests
- Use realistic but anonymized data
### Database Tests
- Use transactions with rollback
- Or use test containers
- Never test against production data
## Reporting
### Test Reports Should Include
- Total tests run
- Pass/fail counts
- Coverage percentage
- Execution time
- Flaky test identification
### QA Report Template
```markdown
# QA Report - Issue #{number}
## Summary
- Tests Added: X
- Tests Modified: Y
- Coverage: XX%
## Test Results
- Passed: X
- Failed: X
- Skipped: X
## Coverage Analysis
- Lines: XX%
- Branches: XX%
- Functions: XX%
## Notes
[Any observations or concerns]
```
## Commit Format
```
test(#34): Add user registration tests
- Unit tests for validation logic
- Integration tests for /api/users endpoint
- Coverage increased from 72% to 87%
Refs #34
```
## Before Completing
1. All tests pass locally
2. Coverage meets 85% threshold
3. No flaky tests introduced
4. CI pipeline passes
5. Update scratchpad with results