diff --git a/docs/decomposition/epics/epic_02_skills_and_progression.md b/docs/decomposition/epics/epic_02_skills_and_progression.md index 549ca28..5c9e63d 100644 --- a/docs/decomposition/epics/epic_02_skills_and_progression.md +++ b/docs/decomposition/epics/epic_02_skills_and_progression.md @@ -29,7 +29,7 @@ Provide a data-driven **non-combat skill** layer: `SkillDef` registry, **skill** - Key contracts: `XpGrantEvent`, `LevelCurve`, `LevelUpEvent` - Dependencies: E2.M1 - Stage target: Prototype -- Note: E3.M1, E3.M2, and E5.M1 integrate by calling this engine; they are not dependencies for implementing E2.M2 (see Slice 3). +- Note: **E3.M1** and **E3.M2** (and mission/reward routers such as **E7.M2**) integrate as **callers** of **E2.M2** for **skill** XP. **E5.M1** resolves **combat** and advances **gig** progression **outside** **E2.M2**—see Slice 3. None of these are **hard** dependencies for implementing the **E2.M2** core (stub callers in Slice 2). ### E2.M3 - MasteryAndPerkUnlocks diff --git a/docs/reviews/2026-04-03-final-branch-docs-review.md b/docs/reviews/2026-04-03-final-branch-docs-review.md new file mode 100644 index 0000000..b64cdec --- /dev/null +++ b/docs/reviews/2026-04-03-final-branch-docs-review.md @@ -0,0 +1,64 @@ +# Final branch documentation review + +**Date:** 2026-04-03 +**Scope:** Full doc + content contract pass for branch **`chore/game-design-docs`** vs **`main`** (game-design vision set, Epic 2 rename and module updates, `content/` skill schema + CI, `docs-review-agent`, PR gate, root README, `.vscode` debug/tasks). +**Base:** `main` (diff as of review); HEAD sample `0dea48e` on `chore/game-design-docs` (verify at merge time). + +## Verdict + +**Approve with suggestions** — Vision and decomposition align on the hybrid **gig vs non-combat skill** model; `SkillDef` schema, prototype catalog, and CI checks are consistent with **E2.M1** / **E2.M2** module text. The **E2.M2** bullet **Note** in **`epic_02_skills_and_progression.md`** was corrected during this review so it no longer implies **E5.M1** calls **E2.M2**. + +## Summary + +The branch tightens the **skills** track around **`allowedXpSourceKinds`**, four **`SkillCategory`** values, and explicit rejection of **combat encounter → skill XP**. Game-design docs (`progression`, `gathering`, `crafting`, `abilities`, `gigs`, `skills`) and **`epic_02_skills_and_progression.md`** agree with **E2.M1** / **E2.M2**. **`zones.md`** and cross-links sit correctly beside **`risk-security-bands.md`** on the **E4.M1** graph. **`scripts/validate_content.py`** and **`scripts/check_decomposition_language.py`** both pass locally. Optional follow-up: one line under **E2.M2** in **`neon_sprawl_vision.plan.md`** for **`sourceKind`** / **`allowedXpSourceKinds`** parity with modules. + +## Documentation checked + +| Path | Result | Notes | +|------|--------|--------| +| `docs/game-design/overview.md` | **Matches** | Artifact index + planned topics coherent; combat stub points to Epic 5 / abilities / items | +| `docs/game-design/progression.md` | **Matches** | Epic 2 Slice 3 = gather/craft → skill XP, combat → gig XP, mission rewards explicit | +| `docs/game-design/skills.md` | **Matches** | Seams anchor `#seams-gigs-skills` present; categories align with schema enum | +| `docs/game-design/gigs.md` | **Matches** | Epic 2 / Epic 5 anchors; PvP open indefinite called out | +| `docs/game-design/gathering.md`, `crafting.md`, `abilities.md` | **Matches** | Epic 2 links use `epic_02_skills_and_progression.md` | +| `docs/game-design/zones.md` | **Matches** | Same graph as tiers; E4.M1 / E7.M4 map | +| `docs/game-design/risk-security-bands.md` | **Matches** | Points to `zones.md` for place fiction | +| `docs/decomposition/epics/epic_02_skills_and_progression.md` | **Matches** | Objective + Slice 1/3/DoD correct; **E2.M2** **Note** updated: E3 callers vs E5 gig path (same session as this review) | +| `docs/decomposition/modules/E2_M1_SkillDefinitionRegistry.md` | **Matches** | Schema table, `allowedXpSourceKinds`, CI pointer | +| `docs/decomposition/modules/E2_M2_XpAwardAndLevelEngine.md` | **Matches** | `sourceKind` validation; E5.M1 → gig XP | +| `docs/decomposition/modules/E2_M3_*.md`, `E2_M4_*.md` | **Matches** | Epic link updated | +| `docs/decomposition/README.md` | **Matches** | Epic 2 row → new filename | +| `docs/decomposition/modules/CT_M1_ContentValidationPipeline.md` | **Matches** | PR gate + scripts described | +| `neon_sprawl_vision.plan.md` | **Partially matches** | Epic 2 title and E2.M1 note OK; E2.M2 could mention **grant channel** validation for parity with modules | +| `content/schemas/skill-def.schema.json` | **Matches** | Required fields + enum align with **E2.M1** | +| `content/skills/prototype_skills.json` | **Matches** | Three rows, distinct categories | +| `content/README.md` | **Matches** | Local validate instructions | +| `.cursor/rules/docs-review-agent.md` | **Matches** | Hybrid ground truth includes `zones.md` | +| `AGENTS.md` | **Matches** | Docs review agent row | +| `README.md` (root) | **Matches** | Gigs + skills one-liner | +| `.github/workflows/pr-gate.yml` | **N/A** (workflow) | Validates content + decomposition language | +| `.vscode/launch.json`, `tasks.json` | **N/A** | Launch targets `server/NeonSprawl.Server.Tests` + `NeonSprawl.sln` at repo root — paths exist | + +## Blocking issues + +None for **merge** from a **documentation correctness** standpoint. + +## Suggestions + +1. **`neon_sprawl_vision.plan.md`** — Optional one-line under **E2.M2**: reject **XP** grants whose **`sourceKind`** is not in the target skill’s **`allowedXpSourceKinds`** (mirrors module + schema descriptions). + +## Nits + +- **`docs/reviews/2026-04-03-game-design-branch-docs-review.md`** verification bullet still mentions grepping **`epic_02_classless_progression`**; repo docs no longer use that path (harmless historical note). +- **`.vscode/launch.json`** retains default .NET template comments — fine for a first drop; team may want a Neon Sprawl–specific label later. + +## Verification + +```bash +pip install -r scripts/requirements-content.txt +python scripts/validate_content.py +python scripts/check_decomposition_language.py +rg 'epic_02_classless_progression' docs/ content/ --glob '*.md' +``` + +Expect **no** hits under `docs/` (except optional old **reviews** text). Spot-check **GitHub** rendering for `docs/game-design/overview.md` and `epic_02_skills_and_progression.md` links after merge.