docs(phase-0): environment assessment, architecture review, and findings #4

Merged

Charon merged 1 commit from feat/phase-0-assessment into main

2026-02-20 23:49:33 +00:00

Clotho commented

2026-02-20 16:14:25 +00:00

Member

Summary

Phase 0 environment assessment and architecture review per issue #2.

FINDINGS.md added — full audit report covering environment, test baseline, code quality, and architecture
TODO.md updated — three new items from findings

Key Findings

P1 Bug: `namespace_id` columns missing from migrations (BUG-001)

entitlement_usage_records and entitlement_boosts tables have no namespace_id column, but EntitlementService::recordNamespaceUsage() and provisionNamespaceBoost() both write to it. Any call to either method will throw a database error at runtime. A migration is needed.

P0 Environment Blocker: `composer install` fails (ENV-001)

host-uk/core is a private dependency with no repositories entry in composer.json. The vendor directory is empty, blocking all tooling (tests, Pint, PHPStan).

P3: 9 files missing `declare(strict_types=1)` (DX-005)

DX-001 only fixed three files — nine more remain non-compliant.

Architecture Documented

BelongsToWorkspace trait: auto-assigns workspace_id, strict-mode enforcement, cache invalidation hooks
WorkspaceScope global scope: auto-filters all queries, fail-safe empty results in non-strict mode
Middleware chain: ResolveWorkspaceFromSubdomain -> RequireWorkspaceContext -> CheckWorkspacePermission
Migration patterns: 6 migrations, 17 tables, composite indexes
Entitlement cascade: namespace-level -> workspace-level -> user tier

Test plan

Review FINDINGS.md for completeness
Open follow-up issue for BUG-001 (namespace_id migration)
Open follow-up issue for ENV-001 (composer repository config)
Merge once reviewed

Closes #2

Generated with Claude Code

## Summary Phase 0 environment assessment and architecture review per issue #2. - **FINDINGS.md** added — full audit report covering environment, test baseline, code quality, and architecture - **TODO.md** updated — three new items from findings ## Key Findings ### P1 Bug: `namespace_id` columns missing from migrations (BUG-001) `entitlement_usage_records` and `entitlement_boosts` tables have no `namespace_id` column, but `EntitlementService::recordNamespaceUsage()` and `provisionNamespaceBoost()` both write to it. Any call to either method will throw a database error at runtime. A migration is needed. ### P0 Environment Blocker: `composer install` fails (ENV-001) `host-uk/core` is a private dependency with no `repositories` entry in `composer.json`. The vendor directory is empty, blocking all tooling (tests, Pint, PHPStan). ### P3: 9 files missing `declare(strict_types=1)` (DX-005) DX-001 only fixed three files — nine more remain non-compliant. ## Architecture Documented - `BelongsToWorkspace` trait: auto-assigns `workspace_id`, strict-mode enforcement, cache invalidation hooks - `WorkspaceScope` global scope: auto-filters all queries, fail-safe empty results in non-strict mode - Middleware chain: `ResolveWorkspaceFromSubdomain` -> `RequireWorkspaceContext` -> `CheckWorkspacePermission` - Migration patterns: 6 migrations, 17 tables, composite indexes - Entitlement cascade: namespace-level -> workspace-level -> user tier ## Test plan - [ ] Review FINDINGS.md for completeness - [ ] Open follow-up issue for BUG-001 (namespace_id migration) - [ ] Open follow-up issue for ENV-001 (composer repository config) - [ ] Merge once reviewed Closes #2 Generated with Claude Code

👍 1

Clotho added 1 commit 2026-02-20 16:14:25 +00:00

docs(phase-0): environment assessment, architecture review, and findings

CI / PHP 8.2 (pull_request) Waiting to run

Details

CI / PHP 8.3 (pull_request) Waiting to run

Details

CI / PHP 8.4 (pull_request) Waiting to run

Details

CI / Assets (pull_request) Waiting to run

Details

cdb7dddd44

Resolves #2 (phase 0 tasks):

- FINDINGS.md: full environment + architecture report
  - composer install blocked by missing host-uk/core repository config
  - test baseline: 15 files / ~4,053 lines (cannot run, vendor missing)
  - code quality: 9 files missing declare(strict_types=1)
  - architecture documented: BelongsToWorkspace, WorkspaceScope, middleware
    chain, migration patterns, entitlement system
  - critical bug identified: namespace_id columns missing from
    entitlement_usage_records and entitlement_boosts migrations

- TODO.md: three new items added
  - BUG-001 (P1): missing namespace_id migration columns — runtime crash
  - DX-005 (P3): strict_types in 9 remaining model/service files
  - ENV-001 (P3): configure host-uk/core repository so composer install works

Co-Authored-By: Clotho <clotho@lthn.ai>