docs: clarify context reading and documentation maintenance rules - #466
Merged
Conversation
Clarify note triggers for implementation, research, and design; preserve read-only task restrictions and existing note ownership. Record the policy in bilingual notes and link the repository map to keep root instructions within budget. Model: gpt-6
Make reading, Spec approval, Agent Note updates, and completion checks explicit in root AGENTS.md. Move catalog explanations into a linked guide while preserving binding rules and update the bilingual process note. Model: gpt-6
zxch3n
added a commit
that referenced
this pull request
Sep 7, 2026
Keep HistoryWriter-specific contracts and repair notes here; the general documentation workflow is reviewed independently in #466. No runtime code changes. Model: gpt-6
Model: gpt-6
zxch3n
marked this pull request as ready for review
September 7, 2026 14:13
zxch3n
added a commit
that referenced
this pull request
Sep 9, 2026
* fix: preserve future history items when sending messages Model: gpt-6 * docs: scope session history invariant to shared package Move the history storage rule next to its schema and tests so the root AGENTS.md stays within the documentation CI size limit. Preserve the rule and add the required CLAUDE.md symlink. Model: gpt-6 * docs: require agent notes for non-trivial work Clarify note triggers for implementation, research, and design; preserve read-only task restrictions and existing note ownership. Record the policy in bilingual notes and link the repository map to keep root instructions within budget. Model: gpt-6 * docs: consolidate documentation workflow in root instructions Make reading, Spec approval, Agent Note updates, and completion checks explicit in root AGENTS.md. Move catalog explanations into a linked guide while preserving binding rules and update the bilingual process note. Model: gpt-6 * fix: temporarily bypass session whole-state validation Disable session Mirror update validation in the renderer and CLI while preserving external input parsing. Cover malformed historical items and both construction sites, and document the temporary tradeoff and replacement contract. Model: gpt-6 * fix: centralize session history writes behind typed boundaries Extract the schema-aware HistoryWriter from #376 and route renderer and CLI history changes through one shared path. Parse new and changed inputs before CRDT operations while preserving untouched incompatible history and existing containers. Keep the full Mirror read path, add compatibility and compile-time regressions, and document the contract. Model: gpt-6 * fix: accept fork origin notices in history writes Add the correlated fork-origin schema and bidirectional notice type coverage. Exercise regular and worktree forks through the real SessionDocument and HistoryWriter; retain malformed metadata rejection and document the prior test gap. Model: gpt-6 * fix: preserve stored history across fork and rollback Separate writer-authored input from writer-captured stored history. Preserve opaque content during forks and guarded edit rollback, with real Loro integration coverage. Model: gpt-6 * fix: preserve history across initialization and read acknowledgements Retain fork setup logs, allow replacement read acknowledgements during rollback, and validate tool state changes without reparsing untouched payloads. Model: gpt-6 * chore: move documentation maintenance changes to PR 466 Keep HistoryWriter-specific contracts and repair notes here; the general documentation workflow is reviewed independently in #466. No runtime code changes. Model: gpt-6 * fix: preserve steer provenance and permission metadata Preserve steer delivery markers through history writes and reads, and validate permission metadata updates independently of legacy tool payloads. Add real-writer regression coverage and update the related specs and notes. Model: gpt-6 * fix: track stored baselines for imported history Keep source hashes and turn identities stable while validating refreshed history against a cursor-bound stored-content baseline. Cover legacy storage, concurrent edits, delayed cursors and conflict resolution with real writer regressions, and document compatibility limits. Model: gpt-6 * fix: preserve peer edits when resolving task proposals Resolve task decisions against the latest history item through HistoryWriter instead of replacing stale entries. Add deterministic replica regressions and document the remaining structural-edit limit. Model: gpt-6 * fix: isolate invalid ACP history inputs and preserve extensions Accept JSON protocol extensions without relaxing known message validation, preserve unchanged legacy tool blocks, and isolate deterministic write failures from subsequent ACP output. Add nested schema contracts, regressions, and implementation notes. Model: gpt-6 * fix: scope history rollback to the changed range Preserve concurrent edits to untouched history rows during edit-and-resend compensation. Add real replica and service regressions and update rollback contracts and notes. Model: gpt-6 * perf: reduce history writer parsing and field update overhead Index discriminated schemas, avoid redundant copies and unchanged-container reads, narrow field updates, and batch initial history writes. Add synthetic benchmarks and document the remaining full-Mirror performance gap. Model: gpt-6 * perf: use target-local history updates for ACP streaming Route targeted text and thought batches through turn-local writes, derive cached single-pass input parsers with refinements retained, and reduce item and stored-copy matching overhead. Add compatibility regressions and benchmarks documenting remaining seed and commit costs. Model: gpt-6 * perf: copy only changed paths for Mirror text events Patch the pinned Mirror reader for single existing text updates while preserving descriptors, snapshots, and notifications. Add real-replica regressions, isolated reader benchmarks, and documentation of remaining bulk-import limits. Model: gpt-6 * fix: preserve queued messages and compatible history edits Normalize legacy selectors on new writes, validate independent field edits locally, retain queue items until history acceptance, and capture only the rollback range while preserving later appends. Add regressions and document remaining recovery limits. Model: gpt-5 * chore: consolidate history writer docs and remove shallow tests Consolidate incremental notes into the bilingual owning record, repair references, remove source-string construction tests, and require behavior-focused tests and compact PR documentation in AGENTS.md. Model: gpt-5 * fix: repair queued turn activation on promotion retry Retain queued messages until history and activation publication succeed. Recover history-only commits without duplicating turns, replaying terminal messages, or replacing another pending activation. Cover metadata failures with a real SessionDocument regression and update the owning documentation. Model: gpt-5 * fix: preserve history input filtering through Zod pipes Traverse both sides of schema pipes while preserving preprocessing, transforms, and refinements. Cover nested config filtering, legacy normalization, stored-history preservation, and invalid-write atomicity with real writer tests. Model: gpt-5 * chore: adopt loro-mirror 2.3.2 Use the released Mirror text-event optimization and remove the temporary 2.3.1 patch. Update the paired React/Jotai packages and lockfile, and record the upstreamed reader path in the owning notes. Model: gpt-5
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.
Related issue
Split documentation/process work from PR #460; no new Issue is required for this same-repository branch.
Problem / pressure
Contributor instructions did not state clearly enough when to read related Specs/notes/docs, record design-only findings, or update Agent Notes. These process changes should be reviewed separately from the HistoryWriter refactor.
Summary
Extract the existing documentation-only commits from #460:
Before / after
Test plan
pnpm run docs statusandpnpm run docs checkpassed.git diff --checkpassed.Context handoff
Instructions for reviewing agents
Authoring context