mosaicstack/stack
1
0
Fork 1
Code Issues 246 Pull Requests 7 Actions Packages Projects Releases 15 Wiki Activity

docs: migrate historical report evidence

Browse Source
This commit is contained in:
Jason Woltje
2026-08-10 18:09:00 -05:00
parent 430b4d5f5d
commit 9f741874bd
4 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reports/code-review/gateway-security-20260313.md
+23
View File
@@ -0,0 +1,23 @@
# Code Review Report — Gateway Security Hardening
## Scope Reviewed
- `apps/gateway/src/chat/chat.gateway-auth.ts`
- `apps/gateway/src/chat/chat.gateway.ts`
- `apps/gateway/src/conversations/conversations.dto.ts`
- `apps/gateway/src/chat/__tests__/chat-security.test.ts`
## Findings
- No blocker findings in the final changed surface.
## Review Summary
- Correctness: socket auth helper now returns Better Auth session data unchanged, and gateway disconnects clients whose handshake does not narrow to a valid session payload
- Security: conversation role validation now rejects `system`; conversation content ceiling is 32k; chat request ceiling remains 10k
- Testing: targeted auth, ownership, and DTO regression tests pass
- Quality: `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all pass after the final edits
## Residual Risk
- `chat.gateway.ts` uses local narrowing around an `unknown` session result because the requested helper contract intentionally returns `unknown`.
docs/reports/compaction-refresh/830-documentation-checklist.md
+34
View File
@@ -0,0 +1,34 @@
# #830 Documentation Completion Checklist
## Required artifacts
- [x] `docs/PRD.md` contains the M1 compaction-refresh trust-lifecycle requirements and acceptance criteria.
- [x] Operator behavior and recovery are documented in `docs/guides/lease-broker-operations.md`.
- [x] Developer architecture and protocol behavior are documented in `docs/architecture/compaction-revocation.md`, `lease-broker-protocol.md`, and `mutator-class-gate.md`.
- [x] Security boundaries and residuals are documented in `docs/architecture/lease-broker-security.md` and `compaction-revocation.md`.
- [x] `docs/SITEMAP.md` links the new architecture page.
- [x] User-guide changes are not applicable: observers are mandatory internal runtime controls with no end-user workflow.
- [x] OpenAPI/endpoint changes are not applicable: the broker remains an internal Unix-socket protocol, not a public HTTP API.
## Contract coverage
- [x] Claude and Claudex lifecycle signals, matchers, commands, and fail-closed behavior are documented.
- [x] Pi pre-/post-compaction signals and session replacement reasons are documented.
- [x] Private generation-file ownership, monotonic update, same-PID replacement, and failure fencing are documented.
- [x] `revoke_lease` input purpose, broker response state, and denial behavior are documented.
- [x] T12b/T30 explicitly names the bounded residual stale window and reports within-TTL **ALLOWED** / after-TTL **DENIED**.
- [x] Documentation explicitly disclaims a within-window mutator-action bound.
- [x] T-A, T-C, same-principal, and protected-branch boundaries are retained.
## Structure and review
- [x] New architecture content is under `docs/architecture/`.
- [x] This report is under `docs/reports/compaction-refresh/`.
- [x] Session evidence is under `docs/scratchpads/`.
- [x] Documentation changes are in the same logical change set as code and tests.
- [ ] Independent exact-head code and Opus security reviews pending coordinator sequencing after the deterministic-main rebase gate.
## Publishing
- [x] Canonical documentation remains in-repository.
- [x] No external publishing target is required for this internal M1 control.
docs/reports/documentation/AUDIT-2026-02-17-framework-consistency.md
+139
View File
@@ -0,0 +1,139 @@
# Mosaic Framework Consistency Audit
Date: 2026-02-17
Scope:
- `~/src/mosaic-bootstrap`
- `~/src/agent-skills`
- Installed runtime check: `~/.config/mosaic`
## Findings
| ID | Severity | Finding | Status |
| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| MF-001 | High | QA rails scripts referenced invalid paths (missing `/qa/` segment) for `qa-hook-handler.sh` calls. | Remediated |
| MF-002 | Medium | Conditional-loading detection was biased to legacy `agent-guides` markers and missed Mosaic `guides`/`Conditional Context` phrasing. | Remediated |
| MF-003 | Medium | Framework spec text still described detection as `agent-guides`-based only. | Remediated |
| MF-004 | Medium | Runtime Claude overlay hardcoded skill count, which drifts over time. | Remediated |
| MF-005 | High | `pr-reviewer` skill used legacy `~/.claude/scripts/git` and `~/.claude/skills` paths. | Remediated |
| MF-006 | Medium | `using-git-worktrees` prioritized `CLAUDE.md` only and ignored Mosaic-first docs (`AGENTS.md`/`SOUL.md`). | Remediated |
| MF-007 | Medium | Marketing skills used `.claude/product-marketing-context.md` instead of Mosaic repo-local path. | Remediated |
| MF-008 | Low | `agent-skills/README.md` manual install/adaptation guidance referenced legacy Claude-only paths. | Remediated |
| MF-009 | Low | Historical creation-log contained stale Claude-specific path examples. | Remediated |
## Remediation Details
### MF-001 (QA rails path correction)
Updated:
- `tools/qa/qa-hook-wrapper.sh`
- `tools/qa/qa-hook-stdin.sh`
- `tools/qa/qa-hook-handler.sh`
- `tools/qa/remediation-hook-handler.sh`
- `tools/qa/qa-queue-monitor.sh`
Change:
- Standardized handler paths to `~/.config/mosaic/tools/qa/...`.
### MF-002 + MF-003 (conditional loading/context detection)
Updated:
- `tools/bootstrap/agent-lint.sh`
- `tools/bootstrap/agent-upgrade.sh`
- `templates/agent/SPEC.md`
Change:
- Detection now recognizes both legacy and Mosaic patterns:
- `agent-guides` (legacy compatibility)
- `~/.config/mosaic/guides`
- `Conditional Loading`
- `Conditional Context`
### MF-004 (runtime overlay drift-proofing)
Updated:
- `runtime/claude/CLAUDE.md`
Change:
- Removed hardcoded skills count text.
### MF-005 (pr-reviewer skill path migration)
Updated:
- `skills/pr-reviewer/SKILL.md`
Change:
- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/tools/git/...`.
- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.
### MF-006 (worktree skill docs hierarchy)
Updated:
- `skills/using-git-worktrees/SKILL.md`
Change:
- Replaced CLAUDE-only checks with `AGENTS.md` / `SOUL.md` (fallback: `CLAUDE.md`).
### MF-007 (marketing context path migration)
Updated:
- `skills/product-marketing-context/SKILL.md`
- All skills referencing product-marketing-context path (bulk update)
Change:
- Standardized context path to `.mosaic/product-marketing-context.md`.
### MF-008 + MF-009 (repo guidance cleanup)
Updated:
- `README.md` (agent-skills)
- `skills/writing-skills/SKILL.md`
- `skills/writing-skills/examples/CLAUDE_MD_TESTING.md`
- `skills/systematic-debugging/CREATION-LOG.md`
Change:
- Standardized references to `~/.config/mosaic/skills`.
- Removed stale Claude-only wording.
## Residual Legacy References (Intentional)
The following legacy references remain in `mosaic-bootstrap` by design and are not inconsistencies:
- Runtime compatibility tooling for Claude home directory management:
- `bin/mosaic-link-runtime-assets`
- `bin/mosaic-clean-runtime`
- `bin/mosaic-doctor`
- `bin/mosaic-sync-skills`
- `bin/mosaic-migrate-local-skills`
- Documentation explaining Claude runtime overlays:
- `README.md`
- `profiles/README.md`
- `adapters/claude.md`
- `runtime/claude/settings-overlays/` (sample overlay; now shipped sanitized under `examples/overlays/`)
These are required to support existing Claude runtime integration while keeping Mosaic as canonical source.
## Verification
Executed checks:
- `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
- Result: no matches after remediation.
- `rg -n "~/.config/mosaic/tools/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
- Result: no invalid old-style QA rail paths remain.
- Installed runtime validation:
- `~/.config/mosaic` contains `tools/git`, `tools/portainer`, `tools/cicd`, `skills`, and `bin` tooling.
docs/reports/qa/gateway-security-20260313.md
+39
View File
@@ -0,0 +1,39 @@
# QA Report — Gateway Security Hardening
## Scope
- Chat HTTP auth guard hardening
- Chat WebSocket session validation
- DTO validation rules for chat and conversation payloads
- Ownership regression coverage for by-id routes
## TDD
- Required: yes
- Applied: yes
- Red step: targeted tests failed on socket session reshaping and DTO role/length mismatches
- Green step: targeted tests passed after runtime and DTO alignment
## Baseline Verification
| Command | Result | Evidence |
| ------------------------------------------------------------------------------------------------------------------------------ | ------ | --------------------------------------------- |
| `pnpm --filter @mosaicstack/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts` | pass | 3 test files passed, 20 tests passed |
| `pnpm typecheck` | pass | turbo completed 18/18 package typecheck tasks |
| `pnpm lint` | pass | turbo completed 18/18 package lint tasks |
| `pnpm format:check` | pass | `All matched files use Prettier code style!` |
## Situational Verification
| Acceptance Criterion | Verification Method | Evidence |
| ------------------------------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Chat controller requires auth and current-user context | source assertion test | `chat-security.test.ts` checks `@UseGuards(AuthGuard)` and `@CurrentUser() user: { id: string }` |
| WebSocket handshake requires Better Auth session | unit tests for `validateSocketSession()` | null handshake returns `null`; valid handshake returns original session object |
| Conversation messages reject non-user/assistant roles | class-validator test | `system` role fails validation |
| Conversation messages enforce a 32k max length | class-validator test | `32_001` chars fail validation |
| Chat request payload enforces a 10k max length | class-validator test | `10_001` chars fail validation |
| By-id routes reject cross-user access | ownership regression tests | conversations, projects, missions, tasks each raise `ForbiddenException` for non-owner access |
## Residual Risk
- No live HTTP or WebSocket smoke test against a running gateway process was executed in this session.