The site catches up with the engine: the phase 16 documentation refresh - #63
Merged
Conversation
Work items 1 and 6 of the phase 16 plan: the gate, trigger, and quest sections move from the getting-started tutorial into a guides-level home placed after "Listeners and flags", each page keeping a complete program under the docs harness. building-an-adventure's first fragment now authors an ungated door and stands alone; the root section forwards to the new guide for items/triggers/quests. The stale "arrive in a later release" sentence dies in the move, replaced by a live same-page reference. pymdownx.snippets gains dedent_subsections so function-body excerpts render at the margin. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
Work item 2 of the phase 16 plan: sessions-commands-events states the shipped victory entrance and moves the lifecycle section after the mode-gating vocabulary it leans on, gains the gate-refusal rejection family; determinism-saves-replay corrects SCHEMA_VERSION to 3 with both migrations, lists the authored session-state blocks a save carries, scopes the ReplayVersionError check, and adds the replay-listener rule — with the spec's replay bullet amended to the observe-only scope the engine actually honors; views-and-visibility names the refusal beat as the third authored channel and promotes the journal-growth section; listeners-and-flags folds the fetch-quest listener and the interpreter into its complete program so both fragments have a runnable twin; authoring-custom-content and ruleset-options reroute authored behavior to the new guide. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
Work item 3 of the phase 16 plan. The TUI example's rendering catches up with the engine: _run iterates result.events (the phase 14 fold already returns everything nested listener-issued commands logged, so the event-log delta idiom's rationale was false) and appends a rejection's authored refusal text after its code; _status renders the active quests with objective states; a journal verb renders PlayerView.journal with clock stamps, exercised by one new milestone.txt line before the closing status. The fastapi example gains snippet markers only (new_session, restore_session, the CreateSession model). No command sequence or draw changed: the phase 5 goldens regenerate byte-identically. tui-crawler.md rewrites the delta-loop prose to the result-envelope contract, teaches quests/journal/refusal rendering and SessionMode.terminal, and unpacks the reward-economics sentence; fastapi-pattern.md gains the served-content section teaching interpreter registration on both paths plus the wire's journal/quests/refusal surfaces, and drops its numeric command count; llm-referees.md gains the "Narrating authored content" section (guidance, beat-weaving, the interpreter, Command.source), completes the authorial surface with the journal/note and quest lifecycle commands, qualifies "never carry baked prose" to engine-baked, and rewords the example-agent roadmap promise to fact. Phase references drop from the example README and create.py. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
Work item 4 of the phase 16 plan. README and docs/index.md advertise the authored surface in sync and align their reference enumerations; the index gains the "What things are called" concepts table and a link to the GitHub changelog. The save/load sentence is corrected on both carriers to the state-restore truth, with replay_game as the separate path and their agreement as the determinism guarantee. Quickstart and index hand-offs name what each page now teaches, with the new guide as the authored-layer destination. The kernel guide takes its job-first title at its renamed path, guides/rules-without-a-session.md, and two guide openings gain a job-first sentence. AGENTS.md gains the four documentation conventions. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
Work item 5 of the phase 16 plan, docstring and comment hunks only: narrative.py names its three current carriers and documents all nine NarrativeBlock fields where the reference renders them; adventure.py's orientation adds the authored-content surfaces and validation's grown reach; triggers.py, quests.py, and gates.py gain the one-way links to the interpreter, the four lifecycle writers, and the two gate carriers; the three grant commands state the selector rule on character_id; CommandResult states the result-envelope fold; DoorEvent.narrative gains its field docstring (the class-level description folds into it); the QuestView/ObjectiveView id and name fields document themselves; and the _record_deaths link to a filtered private member becomes plain prose. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
The Changed bullet covers the result-events loop, the refusal text, the quest status, and the journal verb; the docs-only changes carry no bullets. Closing greps verify zero numeric surface counts and zero phase references across the teaching surface (index, getting-started, guides, front-ends, reference, README, examples); the adaptations register and the changelog keep their provenance citations by design. Full gate green: ruff, pyright, 2240 tests, mkdocs --strict, goldens byte-identical. Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
Finding 1: the gates section now states outright that a gate's journal beat has no consumer — journaling a door is a trigger's job. Finding 4: the three surviving "a la carte" phrasings become "standalone" now that no title introduces the phrase. Findings 2 and 3 were accepted as reviewed (the register/changelog provenance scoping, and the create.py docstring under the development-history sweep). Claude-Session: https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt
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
1 participant
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.
Implements the phase 16 plan (#62): the technical-writer pass over the post-phase-15 documentation. Milestone: a developer who has never seen this repository finds, learns, and correctly uses gates, triggers, and quests from the published site alone — and no published sentence contradicts the shipped library.
What changed
docs/guides/gates-triggers-quests.md, placed after "Listeners and flags" in the navigation — the interpreter reads as the shipped application of the listener pattern the previous guide teaches. Both pages keep complete programs under the docs harness; building-an-adventure's first fragment now authors an ungated door and stands alone, and the stale "arrive in a later release" sentence died in the move.pymdownx.snippetsgainsdedent_subsectionsso function-body excerpts render at the margin.CompleteQueston aconcludes_adventure=Truequest), moves the lifecycle section after the mode-gating vocabulary it leans on, and gains the gate-refusal rejection family; determinism-saves-replay correctsSCHEMA_VERSIONto 3 with both migrations, lists every session-state block a save carries, and adds the replay-listener rule — with the spec's replay bullet amended to the observe-only scope the engine actually honors (the plan's pinned sentence-level amendment, the phase's second and last spec change); views-and-visibility names the refusal beat as the third authored channel; listeners-and-flags folds the fetch-quest listener and the interpreter into its complete program so both formerly twin-less fragments are true excerpts._runiteratesresult.events(the delta idiom's stated rationale was false since the phase 14 fold) and prints a gate's authored refusal text after its code — the(refused:literal both tripwires grep for stands;_statusrenders active quests, and a newjournalverb renders the journal with clock stamps, exercised by onemilestone.txtline. No command sequence or draw changed: the goldens are byte-identical, verified by regeneration. Transcripts were re-captured from the real seed-21 run (byte-identical to the quoted blocks). fastapi-pattern gains the served-content section teaching interpreter registration on both session paths from real excerpts; llm-referees gains "Narrating authored content" (guidance, beat-weaving, the interpreter,Command.source), the completed authorial surface, and the qualified "engine-baked" prose claim. Numeric surface counts and phase references are gone from the teaching surface.guides/rules-without-a-session.md(no redirect, per the plan's declined-items rationale); AGENTS.md carries the four documentation conventions.triggers/quests/gatesto the interpreter, the selector rule on the three grant commands,NarrativeBlock's nine field docstrings,DoorEvent.narrative, the view id/name fields, and theCommandResultfold.Notable decisions
docs/adaptations.md(a decision register whose entries cite phases as provenance, and which the plan pins as gaining no entries) and CHANGELOG history bullets keep their citations. The rubber-duck evaluated this scoping on the merits and endorsed it.examples/tui_crawler/create.pylost its one "Phase 1" docstring reference under the development-history sweep — a comment-only hunk one file beyond work item 3's pinned list, flagged and accepted in review.Review provenance
A skeptical rubber-duck reviewer walked the plan bullet by bullet, verified the six falsified claims dead against source, mechanically checked excerpt discipline and the goldens, re-ran the transcripts, and executed the plan's four blind tasks docs-only (author the three mechanisms; render quests/journal/refusal from the walkthroughs; answer the save/replay question from the determinism guide; index → quest authoring in ≤ 2 clicks) — all four PASS. First-pass verdict SOLID with four non-blocking findings; two (a gate-journal wording softness, three "à la carte" leftovers) were fixed in the address-findings commit and re-verified, two were accepted as reviewed. Final verdict: SOLID.
Gate:
ruff format --check,ruff check,pyright, 2240 tests,mkdocs build --strictall green; goldens byte-identical;SCHEMA_VERSION3 with no new migration; package version untouched; thesrc/diff is docstring hunks only.https://claude.ai/code/session_01Amd9mBvHddPJNVZwChtbKt