mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

feat: Set up security remediation task tracking
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
Details

Browse Source 
- Update CLAUDE.md to point to universal orchestrator guide
- Add docs/tasks.md with 28 tasks across 4 phases:
  - Phase 1: Critical Security (MS-SEC-001 to MS-SEC-010)
  - Phase 2: High Security (MS-HIGH-001 to MS-HIGH-006)
  - Phase 3: Code Quality (MS-CQ-001 to MS-CQ-007)
  - Phase 4: Test Coverage (MS-TEST-001 to MS-TEST-005)
- Add project-specific task-tracking.md reference

Based on comprehensive codebase review (124 findings).
This commit is contained in:
Jason Woltje
2026-02-05 14:58:34 -06:00
parent bbc211f56e
commit b56bef0747
3 changed files with 231 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
CLAUDE.md
View File

@@ -1,6 +1,15 @@
**Multi-tenant personal assistant platform with PostgreSQL backend, Authentik SSO, and MoltBot
integration.**
## Conditional Documentation Loading
| When working on... | Load this guide |
| ---------------------------------------- | ------------------------------------------------------------------- |
| Orchestrating autonomous task completion | `~/.claude/agent-guides/orchestrator.md` |
| Security remediation (review findings) | `docs/reports/codebase-review-2026-02-05/01-security-review.md` |
| Code quality fixes | `docs/reports/codebase-review-2026-02-05/02-code-quality-review.md` |
| Test coverage gaps | `docs/reports/codebase-review-2026-02-05/03-qa-test-coverage.md` |
## Project Overview
Mosaic Stack is a standalone platform that provides:

190
docs/claude/task-tracking.md Normal file
View File

@@ -0,0 +1,190 @@
# Autonomous Task Orchestration
> Load this guide when orchestrating autonomous task completion via `docs/tasks.md`.
## Ownership
**The orchestrator is the sole writer of `docs/tasks.md`.** Worker agents execute tasks and report results — they never read or modify the tracking file.
## Schema Reference
| Column | Format | Purpose |
| -------------- | ---------------------------------------- | ------------------------------------------- |
| `id` | `MS-{CAT}-{NNN}` | Unique task ID |
| `status` | `not-started` \| `in-progress` \| `done` | Current state |
| `description` | Free text | What to do (inline, concise) |
| `issue` | `#NNN` or empty | Gitea issue for requirements context |
| `repo` | Workspace name | `api`, `web`, `orchestrator`, `coordinator` |
| `branch` | Branch name | Git branch for this work |
| `depends_on` | Comma-separated IDs | Must complete before this task starts |
| `blocks` | Comma-separated IDs | Tasks waiting on this one |
| `agent` | Agent identifier | Who is executing |
| `started_at` | ISO 8601 | When work began |
| `completed_at` | ISO 8601 | When work finished |
| `estimate` | `5K`, `40K` | Predicted token usage |
| `used` | `4.2K`, `38.5K` | Actual token usage (fill on completion) |
**Category prefixes:** `SEC` (security), `HIGH` (high priority), `CQ` (code quality), `TEST` (test coverage)
## Orchestrator Core Loop
```
1. git pull --rebase
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, STOP
- Some blocked? → Report deadlock, STOP
5. Update tasks.md: status=in-progress, agent, started_at
6. Spawn worker agent (Task tool) with task details from the row
7. Wait for worker completion
8. Parse worker result (JSON)
9. Update tasks.md: status=done/failed, completed_at, used
10. Commit + push: git add docs/tasks.md && git commit && git push
11. Check context usage
12. If >= 60%: Compact (see below), then go to step 1
13. If < 60%: Go to step 1
```
## Worker Prompt Template
The orchestrator constructs this prompt from the task row and passes it to a worker agent via the Task tool:
````markdown
## Task Assignment: {id}
**Description:** {description}
**Repository:** /home/localadmin/src/mosaic-stack/apps/{repo}
**Branch:** {branch}
**Reference Report:** See `docs/reports/codebase-review-2026-02-05/` for detailed findings.
## Workflow
1. Checkout branch: `git checkout {branch} || git checkout -b {branch} develop && git pull`
2. Implement the fix following existing code patterns
3. Run quality gates (ALL must pass):
```bash
pnpm lint
pnpm typecheck
pnpm test
```
4. If gates fail: Fix and retry. Do NOT report success with failures.
5. Commit: `git commit -m "fix({id}): brief description"`
6. Push: `git push origin {branch}`
7. Report result as JSON (see format below)
## Git Scripts (for issue/PR/milestone operations, NOT raw tea/gh)
~/.claude/scripts/git/issue-view.sh -i {N}
~/.claude/scripts/git/pr-create.sh -t "Title" -b "Desc" -B develop
# Standard git commands (pull, commit, push, checkout) are fine
## Result Format (MANDATORY)
End your response with this JSON block:
```json
{
"task_id": "{id}",
"status": "success|failed",
"used": "5.2K",
"commit_sha": "abc123",
"notes": "Brief summary of what was done"
}
```
## Rules
- DO NOT modify docs/tasks.md
- DO NOT claim other tasks
- Complete this single task, report results, done
````
## Compaction Protocol
**Threshold:** 60% context usage
**Why 60%?** System overhead is ~26% (prompts, tools, CLAUDE.md). Real capacity is ~74%. Triggering at 60% means ~81% actual usage — safe margin before the 91-95% emergency wall.
**After completing each task:**
1. Check context usage
2. If < 60%: Continue to next task
3. If >= 60%: Compact before next task
**Compaction steps:**
1. Update docs/tasks.md with all current progress
2. Commit + push tasks.md
3. Summarize: completed tasks, quality status, remaining queue
4. Clear detailed worker outputs and execution history
5. Resume with next unblocked task
**Compaction does NOT require user permission.**
**Template:**
```
Session Summary (Compacting at 60%):
Completed: MS-SEC-001 (12K), MS-SEC-002 (8K), MS-SEC-003 (10K)
Quality: All tests passing, zero regressions
Remaining: MS-SEC-004 (ready), MS-SEC-005 through MS-SEC-010, Phase 2-4 tasks
Next: MS-SEC-004
```
**Expected:** Context drops from 60% → ~25-30%.
## Error Handling
**Quality gates fail:**
1. Update tasks.md: status remains `in-progress`, add failure notes
2. Re-spawn worker with error context, or mark `failed` and move on
3. If failed task blocks others: Report deadlock, STOP
**Worker reports blocker:**
1. Update tasks.md: note the blocker
2. Skip to next unblocked task if possible
3. If all remaining tasks blocked: Report, STOP
**Git push conflict:**
1. `git pull --rebase`
2. If auto-resolves: push again
3. If conflict on tasks.md: Report, STOP (human resolves)
## Stopping Criteria
**ONLY stop if:**
1. All tasks in docs/tasks.md are `done`
2. Critical blocker preventing progress (document and alert)
3. Absolute context limit reached AND cannot compact further
**DO NOT stop to ask "should I continue?"** — the answer is always YES.
## Phase Structure
**Phase 1 - Critical Security (MS-SEC-001 through MS-SEC-010):**
- Authentication, XSS, error handling, OIDC validation
- Must complete before Phase 2
**Phase 2 - High Security (MS-HIGH-001 through MS-HIGH-006):**
- CSRF, mock data removal, rate limiting, container hardening
- Must complete before Phase 3
**Phase 3 - Code Quality (MS-CQ-001 through MS-CQ-007):**
- Memory leaks, stale closures, boolean bugs, atomic operations
- Must complete before Phase 4
**Phase 4 - Test Coverage (MS-TEST-001 through MS-TEST-005):**
- Critical service tests, widget tests, coverage investigation
- Final verification gate

32
docs/tasks.md Normal file
View File

@@ -0,0 +1,32 @@
# Tasks
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used |
| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | ----- | ------------ | ------------------------ | --------------------------------------------------------------------------------------- | -------------------------------- | ----- | ---------- | ------------ | -------- | ---- |
| MS-SEC-001 | not-started | SEC-ORCH-2: Add authentication to orchestrator API (spawn/kill/status endpoints) | | orchestrator | fix/security-remediation | | MS-SEC-002,MS-SEC-003,MS-SEC-004 | | | | 15K | |
| MS-SEC-002 | not-started | SEC-WEB-2: Fix WikiLinkRenderer XSS - sanitize entire HTML with DOMPurify before wiki-link processing | | web | fix/security-remediation | MS-SEC-001 | MS-SEC-010 | | | | 10K | |
| MS-SEC-003 | not-started | SEC-ORCH-1: Fix secret scanner error handling - return explicit error state instead of false | | orchestrator | fix/security-remediation | MS-SEC-001 | MS-SEC-010 | | | | 8K | |
| MS-SEC-004 | not-started | SEC-API-2/3: Fix guards swallowing DB errors - let Prisma errors propagate as 500s | | api | fix/security-remediation | MS-SEC-001 | MS-SEC-010 | | | | 10K | |
| MS-SEC-005 | not-started | SEC-API-1: Validate OIDC configuration at startup - fail fast if enabled but unconfigured | | api | fix/security-remediation | MS-SEC-004 | MS-SEC-010 | | | | 8K | |
| MS-SEC-006 | not-started | SEC-ORCH-3: Enable Docker sandbox by default, log warning when disabled | | orchestrator | fix/security-remediation | MS-SEC-003 | MS-SEC-010 | | | | 8K | |
| MS-SEC-007 | not-started | SEC-ORCH-4: Add inter-service authentication (orchestrator-coordinator API key) | | orchestrator | fix/security-remediation | MS-SEC-006 | MS-SEC-010 | | | | 15K | |
| MS-SEC-008 | not-started | SEC-ORCH-5/CQ-ORCH-3: Replace KEYS with SCAN in Valkey client | | orchestrator | fix/security-remediation | MS-SEC-007 | MS-SEC-010 | | | | 12K | |
| MS-SEC-009 | not-started | SEC-WEB-1: Sanitize OAuth callback parameters - validate error against allowlist | | web | fix/security-remediation | MS-SEC-002 | MS-SEC-010 | | | | 8K | |
| MS-SEC-010 | not-started | Phase 1 verification: Run security tests, validate all critical fixes | | api | fix/security-remediation | MS-SEC-002,MS-SEC-003,MS-SEC-004,MS-SEC-005,MS-SEC-006,MS-SEC-007,MS-SEC-008,MS-SEC-009 | MS-HIGH-001 | | | | 10K | |
| MS-HIGH-001 | not-started | SEC-WEB-3: Route all fetch() calls through API client for CSRF (ImportExportActions, KanbanBoard, ActiveProjectsWidget) | | web | fix/high-security | MS-SEC-010 | MS-HIGH-006 | | | | 15K | |
| MS-HIGH-002 | not-started | SEC-WEB-4: Remove or gate mock data in production paths (federation, workspaces, teams pages) | | web | fix/high-security | MS-SEC-010 | MS-HIGH-006 | | | | 12K | |
| MS-HIGH-003 | not-started | SEC-ORCH-11: Add rate limiting to orchestrator API with @nestjs/throttler | | orchestrator | fix/high-security | MS-SEC-010 | MS-HIGH-006 | | | | 10K | |
| MS-HIGH-004 | not-started | SEC-ORCH-10: Add Docker container hardening (CapDrop ALL, ReadonlyRootfs, PidsLimit) | | orchestrator | fix/high-security | MS-SEC-010 | MS-HIGH-006 | | | | 12K | |
| MS-HIGH-005 | not-started | SEC-ORCH-12: Add max concurrent agents enforcement with configurable limit | | orchestrator | fix/high-security | MS-SEC-010 | MS-HIGH-006 | | | | 10K | |
| MS-HIGH-006 | not-started | Phase 2 verification: Run security tests, validate all high-priority fixes | | api | fix/high-security | MS-HIGH-001,MS-HIGH-002,MS-HIGH-003,MS-HIGH-004,MS-HIGH-005 | MS-CQ-001 | | | | 10K | |
| MS-CQ-001 | not-started | CQ-API-1/2: Fix memory leaks - WebSocket timer, runner jobs interval | | api | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 10K | |
| MS-CQ-002 | not-started | CQ-ORCH-1: Fix session Map memory leak - cleanup on terminal states | | orchestrator | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 12K | |
| MS-CQ-003 | not-started | CQ-WEB-1/4: Fix stale closures in useWebSocket and useChat hooks | | web | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 15K | |
| MS-CQ-004 | not-started | CQ-WEB-5: Fix boolean logic bug in ReactFlowEditor (?? to \|\|) | | web | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 5K | |
| MS-CQ-005 | not-started | CQ-ORCH-5: Add atomic state transitions with Valkey Lua script | | orchestrator | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 15K | |
| MS-CQ-006 | not-started | CQ-ORCH-6: Fix N+1 queries with MGET batch retrieval | | orchestrator | fix/code-quality | MS-HIGH-006 | MS-CQ-007 | | | | 12K | |
| MS-CQ-007 | not-started | Phase 3 verification: Run all tests, validate code quality fixes | | api | fix/code-quality | MS-CQ-001,MS-CQ-002,MS-CQ-003,MS-CQ-004,MS-CQ-005,MS-CQ-006 | MS-TEST-001 | | | | 10K | |
| MS-TEST-001 | not-started | Add tests for knowledge.service.ts (916 lines, untested) | | api | fix/test-coverage | MS-CQ-007 | MS-TEST-005 | | | | 25K | |
| MS-TEST-002 | not-started | Add tests for admin.guard.ts and embeddings.service.ts | | api | fix/test-coverage | MS-CQ-007 | MS-TEST-005 | | | | 15K | |
| MS-TEST-003 | not-started | Re-enable 23 skipped widget tests in web | | web | fix/test-coverage | MS-CQ-007 | MS-TEST-005 | | | | 20K | |
| MS-TEST-004 | not-started | Investigate coordinator 16% coverage - fix test configuration | | coordinator | fix/test-coverage | MS-CQ-007 | MS-TEST-005 | | | | 15K | |
| MS-TEST-005 | not-started | Final verification: Full test suite, coverage report, quality gates pass | | api | fix/test-coverage | MS-TEST-001,MS-TEST-002,MS-TEST-003,MS-TEST-004 | | | | | 15K | |