Skip to main content

Living Word — The Scribe's Path (Path of Formation) — Acceptance Spec

Status: MERGED + LIVE on prod 2026-06-05 — PR #763 squash-merged; founder approved all net-new theology copy as-is (the 11 strings). CI-wiring of the unit test (test.yml) remains a one-line founder follow-up (OAuth workflow scope). Deployed-preview Playwright 5/5 green (e2e/living-word/scribes-path.spec.ts): Apprentice + craft note + no truths for a new anonymous player; witnessed-truth capture; rank-up fires once on threshold cross; NPC nod fires only when the truth is carried. The e2e caught a real bug pre-merge (the nod was dropped in the default Quick Play mode — fixed by appending after the mode branch). All net-new player-facing copy is // FOUNDER-REVIEW tagged and listed in the PR for theology sign-off before merge (rule #1). CI-wiring of the unit test is a one-line test.yml follow-up (blocked by missing OAuth workflow scope).

Status (original): APPROVED (design) — founder ruled the 4 foundational decisions 2026-06-05. All player-facing copy is theology-sensitive and gated at PR review (rule #1) before merge. Wave: 4 (Reach & retention) — Track D. Rule #17 gate: satisfied by the rulings below. Author: orchestrator, 2026-06-05.

1. Goal​

Turn Living Word's progression from "a number going up" into "a self forming" — a gentle meta-progression across the whole journey that gives a returning player a reason to keep going and a sense of growth. Per the roadmap (Dimension 2): Apprentice → Witness → Scribe, plus "convictions that change NPC reactions" (reframed below as witnessed truths).

2. The load-bearing theology frame (founder ruling — non-negotiable)​

The ladder measures the scribe's CRAFT — how well you've come to know the story and the Scripture — NOT spiritual maturity, sanctification, or standing before God. This honors the game's own DESIGN.md guardrail ("reward completion + consistency + scripture memory, not spiritual ranking"), the AI-Bridge principle, and the no-spiritual-harm rule.

Invariants (all player-facing copy must obey; reviewed at PR):

  • Frame ranks as a learning/craft role (cf. Ezra, "a scribe skilled in the Law" — Ezra 7:6), never as a verdict on the player's faith or soul.
  • Include a plain one-line note where the rank is shown: this reflects your journey through the story, not a measure of your faith.
  • Private to the player only. No leaderboard of ranks, no comparison, no ranking of one person's "formation" against another's. (Completion/streak leaderboards may exist elsewhere; the Scribe's Path is never ranked publicly.)
  • No guilt, no loss of rank, no "you're behind." Advancement only; never demotion.

3. Naming (founder ruling: rename the new system)​

  • New system name: "The Scribe's Path" (working default — founder may adjust the string at PR).
  • The existing in-game rooms keep the name "Formation Spaces" (Cave of Wisdom, House of Table Fellowship) — unchanged. No churn to existing code/UX.
  • Ranks: Apprentice → Witness → Scribe (craft roles; founder may rename any tier at PR).

4. What's there already (audit, verified 2026-06-05)​

  • No rank/level/title system, no convictions, no Apprentice/Witness/Scribe — greenfield.
  • Existing progression = "resolve" (hearts) + "wisdom" XP toasts (not aggregated into a visible rank). Legacy Chain (seed→bloom) is a separate lead-gen feature, not the spine.
  • Save: LWProgressSnapshot (hooks/useCloudSave.ts) — all-optional fields, localStorage (SAVE_KEY) + Supabase game_progress. New fields slot in here, backward-compatible.
  • NPC dialogue is mostly static; DialogueModal already takes player-state props (hasMetHur, hasPlantedSeed, defeatedEnemies) and has 2 existing conditional branches — the v1 "nods" plug in the same way.
  • Local "demonstrated understanding" signals (work for anonymous guests, no cloud needed): defeatedEnemies (you answered correctly to win an encounter), completedCreationDays, solvedPuzzleIds, collectedSecrets, fruitTraits, completedQuests, unlockedSceneIds, explorerProgress (verbs), completedFormations.

5. Design​

5.1 The ladder (founder ruling: knowledge + participation blend; local-signal gated)​

Rank is a pure function of the local save (so it computes identically for anonymous and signed-in players). Blend two axes:

  • Understanding (you've shown you grasp it): count of defeatedEnemies (each requires correct answers to win) + solvedPuzzleIds + completedCreationDays.
  • Participation (you've walked the journey): distinct scenes engaged (unlockedSceneIds / scenes with any explorerProgress or completed quest) + verbs performed + relics collected.

Proposed thresholds (TUNING defaults — adjustable; gentle, reachable by a faithful player):

RankReach when (illustrative)
Apprenticestart (everyone begins here)
Witness~2 scenes engaged AND ~3 encounters won (understanding shown beyond one scene)
Scribe~4 scenes engaged AND ~8 encounters won AND ≥1 verb in ≥3 scenes

Pure helper src/lib/living-word/scribes-path.ts: computeRank(snapshot) -> { rank, progressToNext, signals }. Unit-tested (thresholds, monotonic — never demotes, anonymous-safe). This is the single source of truth.

5.2 Witnessed truths (founder ruling: light NPC nods)​

  • Each flagship scene has a core truth (already authored as the scene's keyVerse / the truth that answers its falsehood). Completing the scene (defeating its shadow) witnesses that truth → appended to witnessedTruths: string[] in the save (idempotent, additive).
  • Light NPC nods (v1, small): a handful of later NPCs acknowledge a truth you carry — one warm line, conditional on witnessedTruths.includes(<id>), surfaced via the existing DialogueModal conditional-branch pattern (like the Adam/hasPlantedSeed addendum). NOT a full dialogue rewrite. Target ~3–5 nods in v1, each grounded in an existing scene truth.
  • Framing: "witnessed truth" = what you saw happen in the story (descriptive of the in-game experience), never "your personal conviction" (which would grade real belief). Reviewed at PR.

5.3 Surfacing (private, non-comparative)​

  • A "The Scribe's Path" section in the existing Progress tool panel (activeTool === 'progress'): current rank, a calm progress indicator toward the next, and the list of witnessed truths. Includes the "reflects your journey, not your faith" note (§2).
  • Rank-up moment: when computeRank crosses a threshold, a gentle, dismissible acknowledgment (reuse existing toast/modal infra), craft-framed copy. No interruption mid-encounter. Exact strings = founder-review at PR.

5.4 Save schema additions (LWProgressSnapshot)​

witnessedTruths?: string[];          // truth ids witnessed by completing scenes
scribeRankSeen?: 'apprentice' | 'witness' | 'scribe';  // last rank we showed a rank-up for

Rank itself is DERIVED (not stored) via computeRank; scribeRankSeen only tracks which rank-up acknowledgment the player has already seen (so we don't re-toast). Both optional → old saves load clean. Persists to localStorage + cloud like the rest.

6. Acceptance criteria (expected outputs)​

  1. A new player is Apprentice; the Progress panel shows the Scribe's Path section with the craft framing note and zero witnessed truths.
  2. Completing a flagship scene's encounter adds its witnessed truth; it appears in the panel.
  3. Crossing a threshold raises the rank (Apprentice→Witness, Witness→Scribe), shows the rank-up acknowledgment exactly once, and the panel reflects the new rank. Rank never decreases.
  4. The rank computes correctly for an anonymous guest (local save only, no sign-in).
  5. At least one NPC nod fires for a player who carries the relevant witnessed truth, and does NOT fire for one who doesn't (behavioral, both directions).
  6. No public ranking of the Scribe's Path anywhere; copy contains no "spiritual maturity"/ sanctification language (theology review passed at PR).
  7. No regression to existing progression (resolve, wisdom toasts, scene unlocks, Legacy Chain).

7. Verification (rules 10, 12, 20)​

  • Unit tests for computeRank (thresholds, monotonicity, anonymous-safe, witnessed-truth capture).
  • Playwright on the deployed preview: seed a save → assert panel rank + witnessed truths; drive a threshold cross → assert rank-up once + panel update; assert an NPC nod fires/doesn't by witnessed-truth state (assert behavior, not just DOM — feedback_verify_behavior_not_dom_presence). Reuse the explorer e2e seeding pattern (localStorage["living-word-progress-v1"] + ?lwAllowTeleport=1&lwExplorerPreview=<scene>).
  • All theology copy (rank names if changed, rank-up text, NPC nods, panel note) approved by founder at the PR before merge (rule #1). DECISION_LOG line; knowledge-sync per rule #16.

8. Scope / deferred​

  • v1 (this spec): rank ladder + computeRank + Progress-panel display + rank-up moment + witnessed-truths capture + ~3–5 NPC nods. All copy founder-reviewed at PR.
  • Deferred: broader NPC dialogue variance across all scenes; any cloud-side rank analytics; tying rank to unlocks/rewards (v1 rank is recognition only, gates nothing — keeps it pressure-free).