settled-reach/docs/sprints/sprint-27/copy.md

title, description, type, status, sprint, team

title	description	type	status	sprint	team
Sprint 27 — Copy Briefing	Author all 29 remaining zone-type behavior templates, replace overheard.yaml, extend validate-ron name collision checking	sprint	active	27	copy

Sprint 27: Scale — Copy Tasks

Goal: Extend the zone-type template library from 2 to 31 zone types, wire the server to load them, and eliminate Clippy debt — clearing the path to the NPC legibility sprint.

Branch: copy Agents: Mellanie (author), Paula (narrative), Gestalt (systems)

New Tickets

#	Title	Blocked by
#662	Author zone-type behavior templates (29 remaining types)	#663 (server structs, soft dependency — can author in parallel, but validate-ron requires server struct changes to pass)
#664	Replace overheard.yaml with generator-compatible conversation system	—
#665	Extend validate-ron to cross-culture name pool collision checking	—

Use tooling/db/ticket show <id> for full details.

Key Decisions

• decisions/content.md — D-142 (zone-type template architecture — primary reference for all authoring in this sprint), D-139 (composable behavior primitives — the three-layer assembly model), D-121 (voice is culture-driven, job as modifier), D-122 (all NPCs generated), D-128 (culture implicit in starting location)
• decisions/scope.md — D-114 (generator-first proof-of-life)

Open Questions to Resolve Early

• Q-WTF-033: AI templating (Claude API vs ollama vs manual) — does not block #662. The primitives authored this sprint are Layer 1 (culture-neutral physical actions). Layer 3 (LLM flavor) is an optional runtime layer; the base text must be fully playable without it. Author for standalone readability per D-142's standalone readability constraint.

Notes

#662 — Author zone-type behavior templates (29 remaining types)

Existing files (done, use as reference):

• content/global/zone-types/rural_agricultural.ron — canonical authoring reference
• content/global/zone-types/industrial_freight.ron

29 remaining zone types to author (canonical list from D-142):

Group	Zone Types
Rural	rural_pastoral, rural_aquaculture, rural_orbital
Industrial	industrial_manufacturing, industrial_processing
Port	port_space, port_surface, port_maritime, port_fishing
Extraction	extraction_space, extraction_surface, extraction_platform
Commercial	commercial_market, commercial_transit
Administrative	administrative_civil, administrative_judicial
Single	research_station, medical_facility, military_garrison, security_checkpoint, entertainment_hospitality, entertainment_venue, residential_station, residential_surface, residential_dispersed, detention_facility, archaeological_site, wilderness_frontier, diplomatic_elite

Authoring rules (non-negotiable, from D-142):

1. Primitives are culture-neutral. Do not encode cultural attitudes, speech patterns, or voice register in action text. "Works a crop row, stopping to pull weeds by the root" is correct. "Works with quiet dignity, as is the Krenn way" is incorrect. Culture is applied by the culture modifier layer at assembly time.

2. Standalone readability constraint. Every action must be informative without a culture modifier. "farms" fails. "kneels at the base of a struggling plant and parts the soil with two fingers" passes. A player reading base text must be able to read what an NPC is doing.

3. ~15 primitives per role, ~4 roles per zone type. (~60 primitives per zone type file, ~1,740 total.) Quality over volume — 12 excellent primitives beats 20 mediocre ones.

4. Context tags: Use OnShift, OffDuty, Social, Any. Most primitives are OnShift. Include at least 3–5 Social primitives per role for tavern/social-site coverage.

5. modifier_hint: Match the seven D-142 categories: work_pace, physical_manner, social_signal, task_completion, environmental_scan, offduty_posture, authority_response. Every primitive should have a hint.

6. Grammar constraint (D-142): Culture modifier clauses attach as prepositional phrases or coordinating conjunctions. Your action text should end in a form that accepts a trailing clause cleanly. "loads a wheelbarrow" → accepts "with unhurried efficiency". Avoid action text that ends in a subordinate clause that would create a grammatically broken assembly.

7. Roles: Each zone type needs roles that match its physical reality. A detention_facility has guard, administrator, prisoner, medic. A research_station has researcher, technician, security, support. Use the zone type's physical space and social function to derive the roles.

8. social_site_types: Every zone type needs at least two social site types. Include one "work" site (workshop, lab bench, loading dock) and one "off-duty" site (break room, canteen, recreation space). List eligible_roles for each.

Validate each file:

tooling/validate-ron content/global/zone-types/<zone_type>.ron zone_type

Note: this requires #663 (server struct changes) to be merged first for validate-ron to accept the zone_type schema. Until then, validate structurally by checking the file matches the pattern in rural_agricultural.ron.

---

Large content push execution — team-patterns.md model:

This is a large batch of structured content (29 files, ~1,740 primitives). Use the parallel writer pattern from docs/ team patterns:

1. Lore librarian agent (read-only): Loads rural_agricultural.ron, industrial_freight.ron, D-142, D-139. Answers authoring questions from writers. Tracks cross-file consistency (do commercial_transit and commercial_market have distinct enough flavor? Does port_space read differently from port_maritime?).

2. Multiple writer agents (parallel, by group): Split by zone-type group:

   • Writer A: Rural (3 files) + Port (4 files)
   • Writer B: Industrial (2) + Extraction (3) + Commercial (2)
   • Writer C: Administrative (2) + Single group part 1 (4 files: research_station, medical_facility, military_garrison, security_checkpoint)
   • Writer D: Single group part 2 (5 files: entertainment_hospitality, entertainment_venue, residential_station, residential_surface, residential_dispersed)
   • Writer E: Single group part 3 (4 files: detention_facility, archaeological_site, wilderness_frontier, diplomatic_elite)

   Each writer writes directly to disk using the Write tool — one file at a time. No text accumulation. Write often.

3. Reviewer agent (after writing complete): Reads all 29 new files + the 2 existing references. Checks: voice consistency (do all zone types read as the same authoring voice?), context tag coverage (are OnShift/Social balanced?), standalone readability (no cultural encoding?), grammar constraint compliance.

Heartbeat rule: If any agent has been working on a single file for more than 15 minutes without progress, message the team lead. Do not silently retry.

---

#664 — Replace overheard.yaml with generator-compatible conversation system

content/npc-conversations/overheard.yaml contains 48 hand-authored conversation entries referencing named v0.1 NPCs (Kael, Sera, Torek, etc.) and the detective arc. Per D-122 (all NPCs generated), this content is superseded.

What to do:

1. Read content/npc-conversations/overheard.yaml to understand its current structure.
2. Design a replacement RON format that supports generator-compatible overheard conversations: no named NPC references, parameterized by role pair and zone type, culture-neutral content that accepts culture modifier at assembly time.
3. Author 10–15 sample overheard conversation snippets in the new format covering at least 3 zone types.
4. Rename/archive the old YAML: content/npc-conversations/overheard.yaml.deprecated with a header comment explaining why.
5. File the new format spec as a note in decisions/content.md if it introduces a new content pattern (check with Qatux).

The old format is not salvageable as-is — the named NPC references make all 48 entries invalid. The structural value (the idea of overheard conversation as an ambient information layer) is worth preserving; the content is not.

---

#665 — Extend validate-ron to cross-culture name pool collision checking

Currently tooling/validate-ron validates individual RON files against their schema. Name pool collisions across culture profiles (a given name appearing in both Krenn and Vael pools) are caught only in PR review.

Deliverable: A new mode in tooling/validate-ron (or a separate tooling/validate-names script):

tooling/validate-ron --check-name-collisions content/global/

This scans all culture-*.ron files, extracts naming.given_names and naming.family_names pools, and reports any name that appears in more than one culture's pool. Output should be machine-readable (exit 1 on collision, print the colliding names and which cultures they appear in).

This is a tooling task. It does not require server changes — the culture RON files are already parseable by the existing validator infrastructure.

---

Dependency Chain

#665 (validate-ron name collision) — standalone, no blockers
#664 (replace overheard.yaml) — standalone, no blockers
#662 (29 zone-type templates) → soft dependency on #663 (server structs) for full validate-ron pass
  └── Parallel writer agents (groups A/B/C/D/E) — all parallel once authoring begins

PR Workflow

When ready to submit, create a PR with tea CLI. All flags are required to avoid TTY prompts (see CLAUDE.md "Gitea access" section):

tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(content): description" --description "body" --base main --head copy