From b56bef07470a00a1e44fe3c8913c815ac090b2ee Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Thu, 5 Feb 2026 14:58:34 -0600 Subject: [PATCH] feat: Set up security remediation task tracking - 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). --- CLAUDE.md | 9 ++ docs/claude/task-tracking.md | 190 +++++++++++++++++++++++++++++++++++ docs/tasks.md | 32 ++++++ 3 files changed, 231 insertions(+) create mode 100644 docs/claude/task-tracking.md create mode 100644 docs/tasks.md diff --git a/CLAUDE.md b/CLAUDE.md index 25346ca..0f8a083 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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: diff --git a/docs/claude/task-tracking.md b/docs/claude/task-tracking.md new file mode 100644 index 0000000..6bc00e5 --- /dev/null +++ b/docs/claude/task-tracking.md @@ -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 diff --git a/docs/tasks.md b/docs/tasks.md new file mode 100644 index 0000000..29445a1 --- /dev/null +++ b/docs/tasks.md @@ -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 | |