zwitschi/security-game
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Reorganize docs into category folders and drop the retired head-review page
Full build / Import + headless tests (push) Successful in 41s
Details
Full build / Full desktop build + optional release (push) Skipped
Details

Browse Source 
Group the top-level docs into docs/project, docs/design, docs/assets and
docs/process, each with its own README index. Delete the superseded
docs/screens/head-review page and sheets. Rewrite every markdown link,
absolute docs path and tool/test reference to the new locations, fix the
pre-existing broken anchors and remove the dead Joke Shop photo-board link.
check_docs OK, Python tooling 167/167.
This commit is contained in:
zwitschi committed 2026-11-06 20:13:03 +01:00
1 parent 045ed2a58f
commit 2ba40f3578
57 files changed
+406 -414
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

TODO.md
+44 -45
View File
@@ -74,7 +74,7 @@ pieces, 20 library props, 6 generated props and the three venue families — plu
pipeline that re-evaluates those venues (OSM data/licensing, reference imagery, the photoreal
facade kit, AI-assisted composing, Gaussian-splatting evaluation and map QA).
**Exit (asset review, A–G):** `docs/3d-model-review.md` scores every catalogue asset; every P0/P1
**Exit (asset review, A–G):** `docs/assets/3d-model-review.md` scores every catalogue asset; every P0/P1
is fixed or explicitly accepted with a measurement; `inspect`/`audit`/`fit`/proportions, the
24-NPC budget and the capture gates are green; no runtime contract, dependency or release artifact
changed except the rebuilt assets themselves.
@@ -111,16 +111,16 @@ licence-free zone only.
(`elcapitan`, `hollywood-block`, `jimmy-kimmel-stage`, `jimmy-kimmel-entrance`,
`comedy-store`).
- [x] Record which local frames changed a decision: added the frame→decision mapping to
`docs/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
`docs/design/venues.md#hollywood-boulevard` (recent `elcapitan-2026` geosearch → 2009 frame stays the
geometry reference; `jimmy-kimmel-entrance/07.jpg` → the four entrance concepts) and
`docs/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
`docs/design/venues.md#the-joke-shop` (`comedy-store/` → the four concept pairs + map plan;
`comedy-store-hillside/` → the day-concept anchor that clears the image-recitation filter).
Frames stay gitignored; only the provenance notes are committed.
### B. Baseline, scorecard and routing
- [x] Load `blender-director` plus the per-family specialists before touching geometry, and
record the skill stack and the advice that changed a decision in `docs/3d-model-review.md`.
record the skill stack and the advice that changed a decision in `docs/assets/3d-model-review.md`.
(Routing, QA severity/verdict, texel-density tiers, character loop criteria and budget rules
recorded in the review doc; MCP-only steps translated to headless flatpak runs.)
- [x] Re-run the neutral NPC baseline (48 frames), the final-context review (96 frames), the
@@ -128,7 +128,7 @@ licence-free zone only.
not replace committed sheets until a fix lands. (48/48 and 96/96 frames captured under
`xvfb-run`, none blank; raw sets in `tmp/model-baseline` and `tmp/model-review`; committed
sheets untouched. 24-NPC smoke still 6.94 ms / 168 meshes / 131,616 triangles.)
- [x] Create `docs/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
- [x] Create `docs/assets/3d-model-review.md` with a per-asset scorecard: silhouette, anatomy/proportion,
topology/edge flow, UV/texel density, textures/materials, rig/weights, LOD/impostor,
collision/grounding, export contract, provenance, skill route, verdict (P0/P1/P2/accept).
(Doc created with character/gear/prop/venue tables, verdict columns and a ranked candidate
@@ -144,11 +144,10 @@ licence-free zone only.
### C. Character re-evaluation (superseded 2026-11-05)
The procedural character review is complete and its evidence stays in
`docs/3d-model-review.md`. The next character pass is the Quaternius base in
[`Milestone 0.9.9`](#milestone-099--quaternius-npc-base-swap-patch) and
[`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch); the open items below are kept
as evidence for what the new base must not regress (face read, hands, weights, cloth, texel
density, crowd variety).
`docs/assets/3d-model-review.md`. The Quaternius base shipped in 0.9.9; the remaining roster
follow-ups are [`Milestone 0.9.10`](#milestone-0910--npc-roster-rollout-patch). The open items
below are kept as evidence for what the new base must not regress (face read, hands, weights,
cloth, texel density, crowd variety).
*Skill route: `character-artist`, `retopology`, `rigging`, `uv-workflow`, `texture-workflow`,
`materials`, `hair-groom`, `asset-optimization`, `lookdev`, `qa-review`.*
@@ -175,7 +174,7 @@ density, crowd variety).
hip fix clean, knee crease minor residual. The guard hip-pouch clip and the residual knee
crease remain as 0.10.0 refinements.
- [x] UV/texel density: measured (64–122 px/m authored, 287–440 px/m effective fabric on the 4×
repeat; table in `docs/3d-model-review.md`). Decision: **accept as-is** — the maps are
repeat; table in `docs/assets/3d-model-review.md`). Decision: **accept as-is** — the maps are
neutral/runtime-tinted (not painted skin), so density controls only subtle weave/noise, and
fabric already sits in the standard tier. No atlas/UDIM/resolution change is justified until
a portrait shows texture starvation; `CHAR_MAX_TRIS`/`CHAR_MAX_VERTS` stay unchanged.
@@ -187,7 +186,7 @@ density, crowd variety).
reconsidered if a later close-up shows visible hem/coat stiffness.
- [ ] Fix only the ranked P0/P1s, one asset family per commit; refresh the comparison sheet and
re-run `inspect`, `audit`, `fit` and `npc_proportions.py` after each fix. **Scheduled: the
remaining character items are covered by Milestone 0.9.9/0.9.10; this row is evidence only.**
remaining character items are covered by Milestone 0.9.10; this row is evidence only.**
- [x] Crowd-variety reference: five licence-cleared Commons photos fetched to
`tmp/research/crowd-variety/` (CC0 ×2, CC BY 2.0, CC BY 3.0, PD) covering umbrella/dense
crowds and a pedestrian mall — general build/hair/outer-layer variety context, reference
@@ -200,7 +199,7 @@ density, crowd variety).
- [x] `qa-review` sign-off: all eight variants **ship with notes** (face realism landed, hands/
cloth/gear accepted, props reviewed); the weights/pose column is the only open item (blocked
on the harness) and the full foliage carded-cluster is the one remaining owner-gated P1.
Recorded in `docs/3d-model-review.md` §qa-review sign-off.
Recorded in `docs/assets/3d-model-review.md` §qa-review sign-off.
### D. Gear and prop re-evaluation
@@ -209,7 +208,7 @@ density, crowd variety).
- [ ] Gear: review the 18 pieces for silhouette, straps/buckles, helmet and lanyard readability
and rebuild only what fails the scorecard. (Attach/clearance verification is done — the
`fit` report is recorded in `docs/3d-model-review.md` with the back-gear-vs-hip-radius
`fit` report is recorded in `docs/assets/3d-model-review.md` with the back-gear-vs-hip-radius
measurement caveat; the visual silhouette read is what remains, pending the owner scorecard.)
- [ ] Props: review the 20 library props plus the 6 generated props for bevels, chamfers,
silhouette, ground contact and shared material language (`prop-artist`, `hard-surface`);
@@ -233,7 +232,7 @@ density, crowd variety).
lamp) and rank the silhouette and proportion mismatches.
- [ ] Rebuild only the mismatched pieces through the assisted Blender pipeline
(`blender_assets.py inspect` → scripted retopo/UV assist → atlas → `audit`/`fit`); document
the exact commands in `docs/asset-tooling.md`.
the exact commands in `docs/assets/asset-tooling.md`.
- [ ] Refresh `sheet_props.jpg`/`sheet_npc_gear.jpg`, the README asset rows and
`docs/blender_previews/README.md` after the rebuilds.
- [ ] Exit: a prop/gear capture sheet, budgets and collision checks pass with no unreviewed asset.
@@ -293,8 +292,8 @@ density, crowd variety).
`tools/three_up.py compose` renders labelled strips into `docs/screens/boards/` (caption
sidecar per board, `rows` emits README rows). Boards committed: El Capitan day, El Capitan
night, Joke Shop day. Tests in `tools/test_three_up.py`.
- [x] Link each committed board from `docs/venues.md#hollywood-boulevard` and
`docs/venues.md#the-joke-shop`.
- [x] Link each committed board from `docs/design/venues.md#hollywood-boulevard` and
`docs/design/venues.md#the-joke-shop`.
- [ ] Use the generated concept lighting and palette as the target for the `lighting`/`lookdev`
pass, and record the deviations that stay accepted.
- [ ] After the pass, regenerate the venue captures and update README plus both venue documents.
@@ -322,10 +321,10 @@ and never ship a generated or downloaded image without provenance.
log and the generated-board reference table. Linked from `docs/screens/README.md`.)
- [x] Hollywood board: five licence-cleared photos (facade day, blade sign, 1922 elevation,
Ovation across street, premiere staging) with a sidecar and per-image purpose, linked from
`docs/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
`docs/design/venues.md#hollywood-boulevard` and credited in `CREDITS.md`. Cropped the foreground crowd
out of the facade shot; EXIF stripped. (`docs/screens/refs/hollywood/`.)
- [x] Joke Shop board: three licence-cleared photos (hillside/canopy block, frontage with palms,
canopy signature band) with a sidecar, linked from `docs/venues.md#the-joke-shop` and credited in
canopy signature band) with a sidecar, linked from `docs/design/venues.md#the-joke-shop` and credited in
`CREDITS.md`. The CC BY-SA `The Comedy Store.jpg` from the old link list was deliberately not
used; the public-domain frames cover the same evidence. (`docs/screens/refs/joke-shop/`.)
**Removed 2026-11-03:** the committed Comedy Store photo board was replaced by the local-only
@@ -333,8 +332,8 @@ and never ship a generated or downloaded image without provenance.
- [x] TV Studio: no separate board — the venue is the same El Capitan Entertainment Centre block as
the Hollywood day shift, restaged for a late-night arrival. The Hollywood board covers both
venues and the premiere-staging photo is the arrival evidence; the reuse is now stated in
`docs/venues.md#hollywood-boulevard`, `docs/gameplay.md`, `PLAN.md` and
`docs/development-status.md`.
`docs/design/venues.md#hollywood-boulevard`, `docs/design/gameplay.md`, `PLAN.md` and
`docs/project/development-status.md`.
- [x] Fill the Hollywood gaps that have a clean licence: El Capitan Theatre neighbour and marquee,
Walk of Fame terrazzo band, star close-up, and a night street-lighting context frame (cropped
to remove people and a plate). The board now has nine photos. (CC BY-SA night frame is
@@ -348,7 +347,7 @@ and never ship a generated or downloaded image without provenance.
preview sheets.)
- [ ] Apply the screenshot rule to every workstream: each accepted fix updates the relevant row in
`README.md` plus the matching docs page (`docs/blender_previews/README.md`,
`docs/screenshots/README.md`, `docs/3d-model-review.md` or the venue map doc).
`docs/screenshots/README.md`, `docs/assets/3d-model-review.md` or the venue map doc).
- [ ] Re-run `tools/check_screenshots.sh` and `python3 tools/check_docs.py` after gallery changes
and record both results in the handoff.
- [ ] Keep AI-generated images out of `assets/` until they are picked, cropped, credited and (for
@@ -372,16 +371,16 @@ and never ship a generated or downloaded image without provenance.
Suite is 275/275.)
- [x] Add a coverage test so every catalogue asset has a scorecard row and verdict.
(`tools/test_model_review.py`: every `CHARACTERS`/`GEAR`/`PROPS` entry needs a row in
`docs/3d-model-review.md`, and character rows need a non-empty verdict.)
- [x] Document the new gates: `docs/blender-assets.md` now lists `texels`, the
`docs/assets/3d-model-review.md`, and character rows need a non-empty verdict.)
- [x] Document the new gates: `docs/assets/blender-assets.md` now lists `texels`, the
`test_model_review.py` coverage gate and the `test_world.gd` collider/proxy gate; skill
routes live in `AGENTS.md` §Local Blender skills and each `TODO.md` section; the scorecard
and evidence table are in `docs/3d-model-review.md`.
- [x] Record accepted limits/deferred rebuilds: `docs/known-limitations.md` already records the
and evidence table are in `docs/assets/3d-model-review.md`.
- [x] Record accepted limits/deferred rebuilds: `docs/design/known-limitations.md` already records the
stylized low-poly style, no finger-curl rig and the >26 m impostor; `MEMORY.md` holds the
durable decisions (texel density accepted, cloth sim out of scope, open palm + forward
offset, face subdivision prototype gated on the owner). The corrected face note is also in
`docs/blender-assets.md`.
`docs/assets/blender-assets.md`.
**Local map workstreams (H–M).** Build a local, data-backed map pipeline that can replace or
supplement the stylized venue geometry with licensed OpenStreetMap footprints, 3D building
@@ -402,7 +401,7 @@ still apply; the map pipeline has its own exit in M.
- [x] ODbL audit: OpenStreetMap is used as **reference only** (hand-built geometry informed by
OSM ways + Commons photos), so the shipped geometry is not an ODbL derived database and no
share-alike obligation attaches. Attribution is still kept via the OSM way links in
`docs/venues.md#hollywood-boulevard` / `docs/venues.md#the-joke-shop`. If derived OSM geometry ever
`docs/design/venues.md#hollywood-boulevard` / `docs/design/venues.md#the-joke-shop`. If derived OSM geometry ever
ships, it needs the attribution + share-alike review in a separate ADR.
- [x] OSM extract workflow: no offline extract is required while OSM is reference-only. If the
pipeline later imports footprints, pin an Overpass query + extract date and record it in a
@@ -501,13 +500,13 @@ Nothing is committed until the licence gate on any promoted reference and the ma
pass. The current `_build_comedy_store_building()` stays as the fallback.*
- [x] Extract the real proportions and reconcile: vision-read `tmp/research/comedy-store/` frames
via `tools/describe_image.py` and recorded the reconciled table in `docs/venues.md#the-joke-shop`
via `tools/describe_image.py` and recorded the reconciled table in `docs/design/venues.md#the-joke-shop`
§Measured proportions. Key finding: the game facade is proportionally **taller** than the
real (3.2:1 vs ~6:1) — the main shape-language deviation; canopy pitch, blade-sign diameter,
entrance and roofline all match closely. Curtain-bay count is crop-dependent (3–7), so 7 is
accepted as a readable stylization.
- [x] Rank the shape-language gaps and write the top-five fix list (measurements from the
proportions pass, §`docs/venues.md#the-joke-shop`):
proportions pass, §`docs/design/venues.md#the-joke-shop`):
1. **Facade height** — game 8.4 m vs real ~5.5–6 m (≈3.2:1 vs ~6:1 ratio). **Fixed
2026-11-03:** `facade_height` lowered to 6.0 m; the wall now reads as a low single-storey
hall with the canopy capping the top (vision-verified).
@@ -533,8 +532,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
top-five list.
- [x] Gates after the rebuild: Godot 277/277 (map budget 26,828 tris / 580 meshes under 150k/700;
navigation/collider tests pass), `tools/check_screenshots.sh` 21 good / 0 bad; the three-up
board and `docs/venues.md#the-joke-shop` were refreshed.
- [ ] Update `docs/development-status.md`, `docs/asset-tooling.md` and `CHANGELOG.md` when the
board and `docs/design/venues.md#the-joke-shop` were refreshed.
- [ ] Update `docs/project/development-status.md`, `docs/assets/asset-tooling.md` and `CHANGELOG.md` when the
rebuild lands; record any accepted deviations from the reference.
### L. Generated location imagery
@@ -575,7 +574,7 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
### M. Local map QA and exit
- [x] Compare the block against screenshots/map docs and keep the stylized fallback: the three-up
boards (photo | concept | capture) and `docs/venues.md#the-joke-shop` record the evidence chain;
boards (photo | concept | capture) and `docs/design/venues.md#the-joke-shop` record the evidence chain;
the procedural `_build_comedy_store_building()` remains the fallback.
- [x] Budget/navigation/collider + day/night captures: Godot 277/277 (Joke Shop 26,828 tris /
580 meshes under 150k/700; navmesh, step collider and prop-collider tests pass),
@@ -583,8 +582,8 @@ pass. The current `_build_comedy_store_building()` stays as the fallback.*
- [x] Gallery + before/after: the Joke Shop day gallery frame and three-up board were recaptured
after each facade change; the photo/concept/capture strip is the before/after record.
- [x] `tools/check_screenshots.sh` re-run (21/0) and the Joke Shop three-up board refreshed.
- [x] Docs: `docs/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
`docs/asset-tooling.md` (`describe_image.py`) and `docs/development-status.md` updated.
- [x] Docs: `docs/design/venues.md#the-joke-shop` (mapping, measured proportions, simplifications),
`docs/assets/asset-tooling.md` (`describe_image.py`) and `docs/project/development-status.md` updated.
`CHANGELOG.md` is untouched (unversioned track; no release).
- [x] Exit: **one local block (the Comedy Store) is reconstructed with reference-derived facades
and massing** — 6.0 m low hall, white signature fascia, tied-back curtains, hotel tower —
@@ -776,7 +775,7 @@ regressing gear fit, budget or readability.
FBX artefacts (per-file armatures, `_end`/`neutral_bone`, node transforms, the shared
jacket/trouser fabric, seam degenerates). `Suit.glb` is the first base: `npc_coat` is now a
dark formal suit instead of a tinted hoodie. The pitfalls are recorded in
`docs/npc-model-sourcing.md` and `MEMORY.md`.
`docs/assets/npc-model-sourcing.md` and `MEMORY.md`.
- [x] **Outfit families rolled out.** Seven more bases intaken (Adventurer, Beach, Casual_2,
Farmer, King, Punk, Suit) with a slot map each: the roster now runs **eleven distinct outfits
across twelve roles**. `patch_slots` buries a hidden triangle for slots a family cannot paint
@@ -833,8 +832,8 @@ accepted on 2026-11-06; the review page and its sheets were then retired.
quads became the light sclera and a shrunken copy pushed along the sclera's own normal became
the dark pupil (`_add_quaternius_eye_whites()`). Two extra draw calls per head, no new UV work.
- [x] Review page re-created for the second pass, then retired after the owner accepted the roster
(2026-11-06). The durable evidence is `docs/3d-model-review.md`, the measurements in
`docs/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
(2026-11-06). The durable evidence is `docs/assets/3d-model-review.md`, the measurements in
`docs/assets/blender-assets.md`, and the `capture_npc_gear.gd` / `capture_npc_baseline.gd` scripts.
- [-] Arm/torso intersection on `npc_dress`/`npc_jacket`/`npc_crowd_a`/`npc_crowd_d`: the baked
rest now aims the upper arm 7° out from vertical. Verified clear on the `casual` base; a
light clip remains on `worker`, so this needs either a wider angle or a per-base shoulder
@@ -871,7 +870,7 @@ contract.
It now reports grip drop, the lowest point at rest against the Quaternius wrist (y 1.017), the
hip-line flag (0.95), the authored size and `size_vs_head` — the proportion number that makes
"reads oversized" measurable.
- [x] Record the nine hand-item measurements (table in `docs/blender-assets.md`). Only the
- [x] Record the nine hand-item measurements (table in `docs/assets/blender-assets.md`). Only the
`clipboard` was actually mis-authored: its grip sat in the *middle* of the board, so it hung
through the thigh line. It now grips the top edge like a carried clipboard (0.22 x 0.30 m).
- [x] Re-author the `clipboard` (top-edge grip, 0.22 x 0.30 m) and rebuild + re-bake AO. The
@@ -885,7 +884,7 @@ contract.
- [x] Retire the gear GLBs the roster no longer uses: `cap` and `hood` are gone from `GEAR`, the
manifest and the asset tree (`beanie` was already retired). The builder branches stay for a
future design, guarded by a comment.
- [x] `docs/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
- [x] `docs/assets/blender-assets.md` documents the 15-piece matrix and the hand-item fit table;
`architecture.md`, `asset-tooling.md` and the preview index were updated with the new counts.
`CREDITS.md` still cites the upstream pack, which is unchanged.
- [x] Owner feedback: the back gear hung at the waist. The `back` attach moved from y 1.10 to
@@ -923,7 +922,7 @@ is signed off.
- [ ] Re-run the 24-NPC budget smoke and the Web/Compatibility capture; record frame time,
mesh/triangle counts and Web load before/after.
- [ ] Retire the procedural variants that are no longer used, keeping one tested fallback; update
`docs/development-status.md`, `docs/3d-model-review.md`, `docs/blender-previews` sheets and
`docs/project/development-status.md`, `docs/assets/3d-model-review.md`, `docs/blender-previews` sheets and
the README character row.
- [ ] Release `0.9.10` with the full procedure (version, changelog, local build, checksums, tag).
- [ ] Shrink the release artifacts: `assets/` alone is ~273 MB in the Linux binary. Excluding
@@ -1026,7 +1025,7 @@ only release-blocking fixes and balance changes may land here.
### Balance and fairness
- [ ] Run the scripted venue sweeps across easy/normal/hard and all four phases using the
`docs/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
`docs/process/release-qa.md#balance-acceptance` targets; tune event weights, reaction tables,
compliance and report strictness where targets fail.
- [ ] Review emergency calls against independent behaviour labels, not `_read_npc_truth()` as its
own oracle; no routine behaviour may make emergency the dominant winning move.
@@ -1052,8 +1051,8 @@ only release-blocking fixes and balance changes may land here.
### Documentation and visual sign-off
- [ ] Update `README.md`, `PLAN.md`, `docs/architecture.md`, the ADRs, `docs/development-status.md`,
`docs/getting-started.md`, `docs/release-qa.md`, `CHANGELOG.md` and this roadmap.
- [ ] Update `README.md`, `PLAN.md`, `docs/project/architecture.md`, the ADRs, `docs/project/development-status.md`,
`docs/process/getting-started.md`, `docs/process/release-qa.md`, `CHANGELOG.md` and this roadmap.
- [ ] Regenerate the gallery and realism baselines from the release-candidate build, not the dev
tree; verify every README/docs image resolves from the tagged build.
- [ ] Run the manual smoke checklist on every target and link the evidence.
@@ -1225,7 +1224,7 @@ Goal: publish the first stable release with a documented compatibility promise.
- [ ] Confirm legal, privacy, rating and storefront approval is complete in writing.
- [ ] Confirm the hardware matrix, accessibility audit and localization sign-off are complete.
- [ ] Confirm no P0/P1 defects remain and every P2 is a documented known limitation.
- [ ] Update `README.md`, `PLAN.md`, `docs/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
- [ ] Update `README.md`, `PLAN.md`, `docs/project/development-status.md`, `CHANGELOG.md`, `CREDITS.md`,
`PRIVACY.md` and the release notes for 1.0.0.
- [ ] Run the full release procedure: version 1.0.0, changelog, clean build, checksum
verification, tag, push and publish.