Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
f857437
docs(roadmap): close merged P02d-6 and record next packet
cemililik Oct 10, 2026
3160714
docs(decisions): accept P02d-7 demo and audit contracts
cemililik Oct 10, 2026
82459cb
feat(dev): add the shared seeded demo lifecycle
cemililik Oct 11, 2026
4966dca
fix(dev): close demo lifecycle review findings
cemililik Oct 11, 2026
6395d85
fix(dev): isolate demo profiles and Compose controls
cemililik Oct 11, 2026
eb3f2da
test(dev): prove demo profile refusal is causal
cemililik Oct 11, 2026
69363fe
test(architecture): enforce the P7 demo identity boundary
cemililik Oct 11, 2026
f54c2f0
fix(architecture): close demo identity scan omissions
cemililik Oct 11, 2026
e70e204
fix(architecture): preserve conditional and runtime census semantics
cemililik Oct 11, 2026
69ce613
fix(architecture): refuse unmodeled resolver options
cemililik Oct 11, 2026
d99d10b
feat(dev): enforce seeded browser and Lighthouse demo proofs
cemililik Oct 11, 2026
38c15d9
fix(dev): refuse incomplete or invisible demo proof results
cemililik Oct 11, 2026
39cee01
fix(dev): join audit output and reject hidden product markers
cemililik Oct 11, 2026
e1486de
fix(dev): preserve the total owned shutdown deadline
cemililik Oct 11, 2026
06d46ad
docs(roadmap): close P7 browser proof review rounds
cemililik Oct 11, 2026
bf5bc9c
feat(ci): enforce P7 public demo and reconcile phase exit
cemililik Oct 11, 2026
100b022
fix(ci): complete P7 exit proofs and reserve owned cleanup
cemililik Oct 11, 2026
8605fc9
docs(roadmap): close both P7 phase-exit review rounds
cemililik Oct 11, 2026
36cd6e0
docs: record P02d-7 CI and phase-exit verification
cemililik Oct 11, 2026
e00395a
docs(roadmap): align locale exit rows with verified CI
cemililik Oct 11, 2026
d47ef17
test(architecture): handle optional demo curricula consistently
cemililik Oct 11, 2026
dca3a7b
fix(dev): align demo tool versions and review evidence
cemililik Oct 11, 2026
aebefee
docs(roadmap): record P7 review remediation verification
cemililik Oct 11, 2026
cd6affd
fix(dev): preserve independent demo cleanup and seed launch
cemililik Oct 11, 2026
db6bcdf
test(architecture): close demo source census admission gaps
cemililik Oct 11, 2026
90114f0
test(architecture): refuse ambiguous demo census resolution
cemililik Oct 11, 2026
c6cd69f
test(web): inspect every inherited demo census config candidate
cemililik Oct 11, 2026
9a0d285
test(dev): verify demo reconciliation and align delivery guidance
cemililik Oct 11, 2026
e3a32d2
docs(roadmap): close systematic P7 remediation review rounds
cemililik Oct 11, 2026
4541d63
docs(roadmap): clarify proof helper closeout wording
cemililik Oct 11, 2026
d16d2d7
test(architecture): admit ignored local machine artifacts
cemililik Oct 11, 2026
9343e99
test(architecture): refuse ignored MSBuild user hooks
cemililik Oct 11, 2026
ec86884
docs(roadmap): close ignored-machine-file review follow-up
cemililik Oct 11, 2026
32a7951
test(cache): coordinate the noncooperative factory timeout proof
cemililik Oct 11, 2026
8d9d219
docs(roadmap): record cache timeout proof reviews
cemililik Oct 11, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions .claude/skills/add-frontend-route/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -315,11 +315,13 @@ records passing production replacement proofs, completed reviews and verified fi
hosts/locales. If unavailable, evidence stays pending and completion is not
claimed. HTTP/RSC assertions are not browser or assistive-technology proof.
P02d-7 owns browser/demo and Lighthouse; Phase 11 owns web-vitals telemetry.
- Lighthouse budget check on representative public routes — CI's `lighthouse budget`
job remains deferred until P02d-7/G44/G45 after P6 pages; judge by reading until
that harness is implemented. Its remaining details are in the
[decision register](../../../docs/roadmap/phase-02d-walking-skeleton.md#the-decision-register);
the pass that closes it rewrites this bullet.
- CI's required `public demo + lighthouse` job exercises the seeded public
catalog/course/lesson routes under
[ADR-0056](../../../docs/decisions/0056-public-demo-browser-and-lighthouse-enforcement.md).
Preserve its production-page admission, hard budgets and owned cleanup. The
[P7 Step 4 record](../../../docs/roadmap/phase-02d-walking-skeleton.md#p02d-7-step-4--ci-enforcement-and-phase-exit-2026-10-11)
owns completed G44/G45 enforcement; Phase 06 still owns broader Playwright/axe
coverage.

## Validation

Expand Down
32 changes: 20 additions & 12 deletions .claude/skills/add-integration-test/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,12 @@ architecture test) plus any other invariant the change touches. See
- Domain-method invariants. Those are unit tests in `LearnStack.Tests.Unit`.
- Structural rules (no cross-module reference). Architecture tests own those.
- UI flows. There is no `LearnStack.Tests.EndToEnd` project. End-to-end means a
browser: Playwright over a running stack, owned by
[Phase 06](../../../docs/roadmap/phase-06-renderer-admin-studio.md) per
[Testing Standards § End-to-End Tests](../../../docs/standards/06-testing.md).
[Phase 02d](../../../docs/roadmap/phase-02d-walking-skeleton.md) puts two
tenants in a browser but gates on a human opening them, not on a Playwright run.
browser over a running stack. P02d-7 supplies the narrow Playwright library
walkthrough of nine seeded product pages and 27 Lighthouse audits through
`make demo DEMO_MODE=ci`; G33's human walkthrough remains separate.
[Phase 06](../../../docs/roadmap/phase-06-renderer-admin-studio.md) owns the
broader Playwright Test/axe suite, per
[Testing Standards § End-to-End Tests](../../../docs/standards/06-testing.md#end-to-end-tests).

## Inputs

Expand All @@ -69,9 +70,12 @@ architecture test) plus any other invariant the change touches. See
> what almost every test wants: **every** migration chain applied — through
> `MigrationChains.ApplyAllAsync`, never a list a fixture keeps itself — and every
> table seeded for two tenants, with a second organization under tenant A. There
> are four chains and seventeen tables as of Packet 9; a fixture that names them is
> a fixture that goes stale, which is the defect below. Share it with `[Collection(SharedSchema.Name)]` rather than
> `IClassFixture<>`, so one container serves the whole schema suite.
> are five chains and 21 data tables (26 including migration histories). Discover
> current chains and history names through
> [MigrationChains](../../../backend/tests/LearnStack.Tests.Integration/Database/MigrationChains.cs);
> do not copy that inventory into a fixture. Share the schema with
> `[Collection(SharedSchema.Name)]` rather than `IClassFixture<>`, so one container
> serves the whole schema suite.
>
> Anything touching either carries `[Trait(RequiresDocker.Key, RequiresDocker.Value)]`,
> which is how CI routes it to `backend-integration` rather than `backend`.
Expand Down Expand Up @@ -225,7 +229,11 @@ and removes every other `ITestOnlyController`. That is the precedent
`ProductionHostFixture` is the counterpart that adds none, so the production
endpoint set stays exactly what a deployed instance serves. It drives the real
middleware chain and the real EF
query filters without moving Phase 02d's first `/api/v1/*` read endpoints earlier.
query filters. Current production Education reads are covered separately by
[PublicEducationHttpTests](../../../backend/tests/LearnStack.Tests.Integration/Database/PublicEducationHttpTests.cs);
[EducationIsolationTests](../../../backend/tests/LearnStack.Tests.Integration/Database/EducationIsolationTests.cs)
independently exercises EF and raw RLS scope, writes and parent guards. Follow
those shipped examples for Education rather than inventing an authenticated route.

### Step 3: Outbox round-trip

Expand All @@ -237,9 +245,9 @@ query filters without moving Phase 02d's first `/api/v1/*` read endpoints earlie
> [ADR-0037 Amendment 1](../../../docs/decisions/0037-idempotency-key-contract.md)
> names: the first `[Idempotent]` endpoint, or the first deployment running more
> than one instance. Packet 6 shipped the `idempotency_keys` table, not the store. The `_fx.*` members below are illustrative of what those phases will
> provide; today the only fixtures are `PostgresFixture` and `SchemaFixture`, and
> the only session-context helper is `SchemaQueries`. Write against Step 1 and
> Step 2's shapes until the owning phase lands.
> provide. The schema examples above use `PostgresFixture`, `SchemaFixture` and
> `SchemaQueries`; production public HTTP cases use the separately shipped fixtures
> linked above. Write against those delivered APIs until the owning phase lands.

For a handler that publishes an integration event:

Expand Down
6 changes: 4 additions & 2 deletions .claude/skills/add-page-block/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,8 +219,10 @@ the page.
[Step 4 record](../../../docs/roadmap/phase-02d-walking-skeleton.md#p02d-6-step-4-product-proof-and-accessibility-closeout)
records product proofs and the scoped manual browser/screen-reader checks.
- [Performance Standards](../../../docs/standards/15-performance.md) governs pages
embedding the block. Accepted G44 assigns Lighthouse activation and assertions
to P02d-7 after P6; the job remains disabled until that harness ships.
embedding the block. P02d-7's shared `make demo DEMO_MODE=ci` proof supplies
nine-page browser/Lighthouse checks; follow
[run-tests-locally](../run-tests-locally/SKILL.md#public-demo-managed-browser-and-lighthouse)
for prerequisites and evidence scope. Phase 06 owns full Playwright Test/axe.

## Validation

Expand Down
2 changes: 1 addition & 1 deletion .claude/skills/code-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ change.
| Outbox round-trip test for new integration event | Always |
| Permission denied test for every new permission key | Always |
| Boundary tests for every DSL band threshold | Scoring / completion rules |
| Lighthouse / axe-core for public-route changes | Accepted P02d-5 G44 assigns Lighthouse activation to P02d-7/G44/G45 after P6 pages. It is still a disabled placeholder; no passing audit is claimed. Accepted P02d-6/G43 requires applicable jsx-a11y error rules with planted controls, actual-page semantics and real manual keyboard/focus/reflow/contrast/screen-reader evidence; the broader axe/Playwright suite belongs to Phase 06. Pending manual evidence prevents packet completion. |
| Lighthouse / axe-core for public-route changes | P02d-7 supplies the shared `make demo DEMO_MODE=ci` seeded browser/Lighthouse proof under ADR-0056; follow run-tests-locally for prerequisites and review its sanitized receipt/reports. Accepted P02d-6/G43 requires applicable jsx-a11y error rules with planted controls, actual-page semantics and real manual keyboard/focus/reflow/contrast/screen-reader evidence; the broader axe/Playwright suite belongs to Phase 06. Pending manual evidence prevents packet completion. |

A change without tests is incomplete; flag as Blocker unless the user
explicitly deferred the test.
Expand Down
24 changes: 15 additions & 9 deletions .claude/skills/implement-task/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,12 +162,15 @@ match the change:

- Backend changes → `dotnet build`, `LearnStack.Tests.Architecture`,
`LearnStack.Tests.Unit`, `LearnStack.Tests.Integration` (Testcontainers).
- Frontend changes → `pnpm lint`, `pnpm typecheck` and `pnpm test`. No Lighthouse
command exists yet, locally or in CI — the `lighthouse-budget` job is a deferred
placeholder — so judge public-route budgets against
[Performance Standards](../../../docs/standards/15-performance.md) by reading. There
is no `pnpm test:a11y` yet
— the axe suite arrives in Phase 06 ([run-tests-locally](../run-tests-locally/SKILL.md)).
- Frontend changes → `pnpm lint`, `pnpm typecheck` and guarded `pnpm test`.
Public-route changes also use the shared P7 browser/Lighthouse lifecycle:
`(cd frontend && pnpm exec playwright install --with-deps chromium)`, then
`make demo DEMO_MODE=ci` from a fresh checkout without private `.env`/
`.env.local` configuration or `artifacts/public-demo`. Follow
[run-tests-locally](../run-tests-locally/SKILL.md#public-demo-managed-browser-and-lighthouse)
for prerequisites, artifact review and cleanup. The Playwright library proof
covers nine seeded pages and 27 audits; Phase 06 owns the full Playwright Test/
axe suite. There is no `pnpm test:a11y` or `pnpm test:e2e` script.
- Documentation-only → broken-link sweep + `docs/analysis/` residual scan
(see Step 7's link audit).

Expand Down Expand Up @@ -264,9 +267,12 @@ template. The prompt must:
Deliver the prompt as a code-fence in the response so the user can copy and
dispatch it.

**Lighthouse ownership — Accepted P02d-5, 2026-10-08.** P02d-7/G44/G45
activates the full-stack job after P6 pages; it remains a disabled placeholder.
The entry decision does not provide a Lighthouse command or passing audit.
**Lighthouse ownership — P02d-7 / ADR-0056.** The shared demo lifecycle supplies
browser/audit proof. The packet's Step 4 record and
[branch protection](../../../.github/CONTRIBUTING.md#branch-protection-settings-on-main)
own real CI receipts and required-check activation; local success alone does not
establish activation. Automated accessibility scores preserve P6's independently
recorded human/VoiceOver evidence and do not claim full WCAG conformance.

## Validation (Definition of Done)

Expand Down
51 changes: 37 additions & 14 deletions .claude/skills/local-dev-setup/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@ description: >
`docker-compose` plus the project's `make dev` orchestrator. USE FOR: first-time
workstation setup, restoring a broken local environment, switching between
`DeploymentMode` for testing. DO NOT USE FOR: production deployment (separate
topic), CI environment configuration (CI uses Testcontainers directly), or
topic), CI environment configuration (integration uses Testcontainers; P02d-7
owns the compose-backed demo), or
cloud / managed equivalents (those are deployment-mode-specific composition).
---

Expand Down Expand Up @@ -39,8 +40,8 @@ the backend runs today calls them, so `make dev` starts 7 services and
## When not to use

- Production deployment. Topic for ops runbooks, not this skill.
- CI configuration. CI uses Testcontainers via `LearnStack.Tests.Integration`,
not `make dev`.
- CI configuration. Integration uses Testcontainers; P02d-7 separately owns
the isolated compose-backed demo and browser/audit job.
- Cloud-managed services (AWS RDS, Confluent Cloud). Composition is similar but
config differs; out of scope.

Expand Down Expand Up @@ -177,8 +178,9 @@ docker compose --env-file .env -f infra/compose/dev.yml config --format json

### Step 4: First-run bootstrap

`make seed` brings the stack up, applies migrations (it depends on `migrate`),
checks the two Keycloak realms, and — since Phase 02a Packet 7 — writes the two
`make seed` starts the selected stack, waits for PostgreSQL before migrations,
checks all seven default services and both Keycloak realm issuers, and — since
Phase 02a Packet 7 — writes the two
demo tenants. One command from a clean checkout.

[SeedData](../../../backend/src/LearnStack.Tools.Seeder/SeedData.cs) owns the exact
Expand All @@ -187,7 +189,24 @@ built-in and tenant-authored definitions, branding and Course/Lesson content.
[seed-tenant](../seed-tenant/SKILL.md) owns convergence, mismatch handling and future
data scope. A completed rerun is write/audit-neutral; a divergent run fails without
overwriting or resetting authored state. Public reads are delivered by P02d-4;
seed alone does not deliver pages.
P02d-6 delivers pages, and P02d-7 starts them with `make demo` after the manual
TLS/hosts prerequisite. Seed alone does not start a renderer.

P02d-7 also supplies isolated CI mode over the same production lifecycle. In a
fresh checkout without root `.env`, web `.env.local` or `artifacts/public-demo`:

```bash
(cd frontend && pnpm install --frozen-lockfile)
(cd frontend && pnpm exec playwright install --with-deps chromium)
make demo DEMO_MODE=ci
```

This creates disposable private TLS/configuration and a unique tmpfs-backed
Compose project, then runs nine browser pages and 27 Lighthouse audits with its
Keycloak stopped. It removes only owned resources and requires successful cleanup.
Follow [run-tests-locally](../run-tests-locally/SKILL.md#public-demo-managed-browser-and-lighthouse)
for fresh artifacts, receipts and prerequisites. Manual hosts/CA trust remains the
human local-mode prerequisite; CI mode does not modify system hosts or trust.

### Step 5: Verify

Expand All @@ -211,8 +230,9 @@ curl -fsS https://localhost:3000/api/healthz
```

P02d-5 delivers native ingress/TLS, live-host bootstrap and enabled-locale entry.
P02d-6 owns public page composition and P02d-7 owns the two-host browser harness.
TLS socket tests with isolated trust roots do not claim a workstation browser run.
P02d-6 supplies public page composition and P02d-7 supplies the narrow two-host
browser/Lighthouse proof. TLS socket tests with isolated trust roots remain
separate from browser evidence and P6's recorded manual accessibility checks.

### Step 6: Switch deployment modes locally

Expand Down Expand Up @@ -244,8 +264,8 @@ separately configured runtime credential. For the paired renderer workflow, rest
with `make public-api` so its child-only database and hop configuration is retained:

```bash
# In the terminal running `dotnet run`, press Ctrl+C, then:
dotnet run --project backend/src/LearnStack.Api
# In the paired API terminal, press Ctrl+C, then:
make public-api
```

### Step 7: Common troubleshooting
Expand Down Expand Up @@ -273,17 +293,20 @@ state.

[ADR-0053](../../../docs/decisions/0053-trusted-public-server-rendering.md)
and the [P5 package](../../../docs/roadmap/phase-02d-walking-skeleton.md#p02d-5-decision-package-2026-10-08)
own the accepted host/TLS/transport contract. `make demo` remains P02d-7/G45.
own the accepted host/TLS/transport contract. P02d-7 supplies foreground `make demo`
and CI browser/audit mode. Follow README Quickstart for production-build launch,
owned cleanup, retained local data and stale-lock handling. The packet's Step 4
record and CONTRIBUTING own real CI receipts and required-check activation.

- `make dev` exits 0; after starting the API separately, `/healthz` responds 200.
- After `make dev-gated` and with that API running, APISIX forwards `/healthz`.
- After explicit local trust/leaf setup, the native HTTPS `/api/healthz` returns 200.
- Direct stock Next cannot authenticate forged ingress carriers; ordinary
`pnpm dev/start` use the mandatory launcher.
- Keycloak login works for both realms.
- `dotnet test backend/tests/LearnStack.Tests.Integration` passes against the
same containers (the Testcontainers fixture is independent; this is just a
consistency check).
- `dotnet test backend/tests/LearnStack.Tests.Integration` passes against its
independently provisioned Testcontainers databases; it does not use the dev
Compose database. P7's demo proof separately exercises the Compose topology.

## Common pitfalls

Expand Down
Loading
Loading