Audit packages 5+6: docs/skills refresh + CI hardening (incl. a real drift fix found by alembic check)#204
Merged
Conversation
Docs/skills (audit Paket 5): - .claude/commands/prime.md rewritten from the current repo layout (described the pre-library-schema world) - verify-api aligned with reality (admin-gated /fit+/quality, four seeded sources, /write/* + /quiz-words + /bboxes/status sweep); verify-core drops stale counts; verify-frontend drops the obsolete favicon-404 gotcha; write-docs matches the real docs/index.md - CLAUDE.md corrections (font-first hero, koch-1928 live source, migration 0008, known-gaps update) mirrored to copilot-instructions (CI = three jobs); naming-und-setup §1 Suetterlin pivot; index.md prose completed; frontend-stack HeroWritten + 'keine eigene Komponenten-Bibliothek'; animation-rendering render-cache path; contributing.md feature set; sprachregelung EN-proposals exception - new docs/reference/write-api.md graduates the shipped /write/* endpoints from the proposal into a reference doc CI hardening (audit Paket 6): - migrations job: + alembic check (drift) + downgrade/upgrade roundtrip; new /verify-migrations skill runs the same sequence locally against a throwaway Postgres - the very first alembic check caught a real drift: 0010 forgot nullable=False on quiz_words.created_at — fixed by migration 0013 - post-deploy smoke step in api/cloudbuild.yaml (health, styles, write/word, 401 write gate) - frontend coverage: vitest --coverage + Codecov frontend flag; app/ no longer codecov-ignored - Node 22 in CI (20 is EOL), engines >=22 - REGEN_SHAPING=1 regen path for the shaping-twin fixture - pre-commit config (ruff check + format) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012RjxGFmMybaLQ4e88qg6jE
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR delivers audit packages 5–6 by refreshing the repo’s docs/agent surface to match the current architecture and hardening CI/tooling around migrations, deployment smoke checks, and frontend coverage reporting.
Changes:
- Harden CI migrations and add drift detection + downgrade/upgrade reversibility checks; add a corrective Alembic revision (0013) for
quiz_words.created_atnullability drift. - Add/refresh documentation and agent skills (incl. new Write-API reference doc and
/verify-migrationsskill) to reflect the current system. - Improve tooling/CI for the frontend: Node 22, Vitest coverage upload to Codecov under a
frontendflag, and add pre-commit Ruff hooks + a shaping-fixture regen path.
Reviewed changes
Copilot reviewed 23 out of 25 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| tests/test_tri_script.py | Adds REGEN_SHAPING=1 path to regenerate the shared shaping fixture from Python shaping logic. |
| docs/reference/write-api.md | New reference doc for the shipped public /write/* endpoints and their pipeline/wire semantics. |
| docs/reference/sprachregelung.md | Documents the exception allowing English research notes in docs/proposals/ when explicitly marked. |
| docs/reference/frontend-stack.md | Updates naming/details to match current landing hero component and design-system positioning. |
| docs/reference/animation-rendering.md | Updates the implemented animation data path (render cache via /write/glyphs, not /diagnostic). |
| docs/index.md | Indexes the new Write-API doc and fills in prose sections for key concept/reference docs. |
| docs/contributing.md | Updates the “live site” feature list to reflect the current public surface. |
| docs/concepts/naming-und-setup.md | Updates MVP validation narrative to reflect the Sütterlin pivot and seeded sources. |
| codecov.yml | Adds a frontend coverage flag/status and stops ignoring app/ coverage by default. |
| CLAUDE.md | Syncs repo overview/skills/known-gaps text with current architecture and the new migrations loop. |
| CHANGELOG.md | Adds [Unreleased] entries describing the CI/skills/docs/tooling changes and migration fix. |
| app/package.json | Bumps Node engine to >=22 and adds @vitest/coverage-v8. |
| app/package-lock.json | Locks the new coverage dependency and updates engines metadata to Node >=22. |
| api/cloudbuild.yaml | Adds a post-deploy smoke step probing key read paths and the admin gate behavior. |
| alembic/versions/0013_quiz_words_created_at_not_null.py | New revision tightening quiz_words.created_at to NOT NULL to resolve alembic drift. |
| .pre-commit-config.yaml | Adds local Ruff pre-commit hooks aligned with CI Ruff checks. |
| .gitignore | Ignores app/coverage/ output. |
| .github/workflows/ci.yml | Adds alembic check + downgrade/upgrade roundtrip, bumps Node to 22, and uploads frontend coverage to Codecov. |
| .github/copilot-instructions.md | Syncs instructions with new migrations job/skill and updated CI job structure. |
| .claude/skills/write-docs/SKILL.md | Updates docs layer tree and indexing rules to match current docs/ structure. |
| .claude/skills/verify-migrations/SKILL.md | New skill documenting the local migration verification loop matching CI. |
| .claude/skills/verify-frontend/SKILL.md | Updates verification guidance (sources list, quiz boot path, favicon 404 is now a regression). |
| .claude/skills/verify-core/SKILL.md | Updates expected pytest guidance to avoid stale test-count assertions. |
| .claude/skills/verify-api/SKILL.md | Updates endpoint sweep expectations, seeded sources, and admin-gated /fit//quality guidance. |
| .claude/commands/prime.md | Refreshes “project primer” to match current layout, routers, and architecture decisions. |
Files not reviewed (1)
- app/package-lock.json: Generated file
Copilot review: the PUT-with-empty-body probe could in principle race
request-body validation; the admin-gated GET has no body, so the 401
assertion is unambiguous. (Empirically the decorator dependency fires
before body validation — the HTTP gate tests pin exactly that with {}
bodies — but the GET probe is robust against future ordering changes.)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012RjxGFmMybaLQ4e88qg6jE
- the smoke's /styles and /write/word calls can be the first real DB request after the min-instances=0 cold start (/health never touches the DB) — all probes now share the retry policy - migration 0013 backfills explicit NULLs before SET NOT NULL (the column was nullable since 0010, server_default does not protect against an explicit NULL insert); full local sequence re-verified (upgrade + check + downgrade roundtrip) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012RjxGFmMybaLQ4e88qg6jE
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Packages 5 and 6 from the July full audit — the documentation/agent-surface refresh and the CI/tooling hardening. Follows the merged #202 (packages 1–4).
CI hardening (Paket 6)
alembic upgrade headit now runsalembic check(model↔migration autogenerate drift) and adowngrade -1/upgrade headroundtrip against its throwaway Postgres 16 — a model column added without a revision, or a broken downgrade, reds CI instead of reaching the shared Cloud SQL instance.alembic checkcaught a real drift: migration 0010 forgotnullable=Falseonquiz_words.created_at(0004 declares it on every othercreated_at; the model implies NOT NULL). New migration 0013 tightens the column — safe, it carriesserver_default=now()./verify-migrationsskill runs the exact CI sequence locally (Docker variant + the web container's unprivileged-Postgres variant, both verified in this session) — closes the Alembic entry in CLAUDE.md's "known gaps without a loop".api/cloudbuild.yaml:/health,/stylesnon-empty,/write/word?text=lesenreturns items, and an uncredentialed write answers 401 — a bad image that still answers /health can no longer ship silently.npm run test -- --coverage(@vitest/coverage-v8) uploads under a new Codecovfrontendflag (informational patch status to start);app/is no longer codecov-ignored.enginesbumped to>=22.REGEN_SHAPING=1regen path for the shaping-twin fixture (mirrors the compose-golden pattern — no more hand-editing JSON that two suites assert).ruff-check+ruff-format(same version CI pins).Deliberately omitted:
paths-ignorefor docs-only PRs — with branch protection it can leave required checks pending forever; noted in the audit as a conscious skip.Docs/skills refresh (Paket 5)
.claude/commands/prime.mdrewritten from the current repo layout (it still described the pre-library-schema world:glyphs.pyrouter,constants.ts,state.tsx,ChartPage).verify-apialigned with reality:/fit+/qualityare admin-gated (the documented public 200 is now correctly a 401 probe), four seeded sources, the sweep covers/write/glyphs,/write/word,/quiz-wordsand the new/bboxes/status.verify-coredrops stale test counts ("29 tests" → shape-based expectation);verify-frontenddrops the obsolete favicon-404 gotcha (favicon ships since 2026-07 — a 404 is now a regression) and describes the render-cache quiz boot.write-docsmatches the realdocs/index.mdstructure (notes/IS indexed;schriftkunde/added to the layer tree)..github/copilot-instructions.md(CI = three jobs,/verify-migrationsin both skill lists).naming-und-setup.md§1 reflects the Sütterlin pivot (it still claimed "MVP validiert an Kurrent allein; nur Loth hat Tafel-Bytes").docs/index.mdprose sections complete (style-guide, design-system, federmodelle, qualitaetsmetrik were tree-only);frontend-stack.mdnamesHeroWrittenand rephrases §8 to "keine eigene Komponenten-Bibliothek";animation-rendering.md§1 describes the actual render-cache data path;contributing.mdnames the full live feature set;sprachregelung.mddocuments the EN-proposals exception.docs/reference/write-api.md: the shipped/write/glyphs+/write/wordendpoints graduate from the proposal into a proper reference doc (pipeline, wire format, cache semantics incl. the documented CDN staleness window,missingsemantics, render-cache consumption), indexed indocs/index.md.Verification
uv run --extra test pytest: 352 passed; ruff check + format clean;npm run lint/npm run buildgreen.alembic check("No new upgrade operations detected." after 0013) → downgrade/upgrade roundtrip — all green.npm run test -- --coverageproducescoverage-final.json(path wired into the Codecov step);app/coverage/gitignored.🤖 Generated with Claude Code
https://claude.ai/code/session_012RjxGFmMybaLQ4e88qg6jE
Generated by Claude Code