Repository navigation
fix(hive): avoid rewriting generated docs during runtime operations - #474
Merged
chaitanyagiri merged 1 commit intoOct 2, 2026
Merged
Conversation
- make ensureHive() create PROTOCOL.md and COMMANDS.md only when missing - add an explicit refreshGeneratedDocs() path for generated hive docs - refresh generated docs only during bootstrap - add generated notices to PROTOCOL.md and COMMANDS.md - add regressions for writeTasks(), ensureAgent(), explicit refresh, and missing-doc recovery
DannyBaanks
pushed a commit
to DannyBaanks/ISyCo-Worlds
that referenced
this pull request
Sep 25, 2026
…h on bootstrap M1 property 5. Upstream evidence: HarnessMD/munder-difflin#474 (cited as evidence of the property, NOT ported as code). ensureHive() mixed two responsibilities: making the hive skeleton exist, and refreshing the two generated docs. But ensureHive is on the runtime path — ensureAgent and writeTasks both call it — so saving one card or spawning one agent silently rewrote PROTOCOL.md and COMMANDS.md, the files every agent is told to treat as the authority. A local edit made on a real floor was reverted with nothing in the log to say so. Split in two: ensureHive creates them when absent, and the new refreshGeneratedDocs() replaces them. The refresh keeps its original purpose — this repo's own hive once carried a protocol file from the day it was initialised, so every protocol change since had reached new hives only — by running where a change can actually land, app start. bootstrapHiveServices() calls it right after ensureHive, and nothing on the runtime path does. New suite test/hive-generated-docs.test.cjs: a fresh hive still gets both files, writeTasks and ensureAgent leave a locally edited copy alone, the explicit refresh does replace it, and the refresh is wired to app bootstrap. before (docs rewritten inside ensureHive): 1 pass / 4 fail after: 5 pass / 0 fail Gates: typecheck exit 0, check:links ok, test:focused 1045 pass / 0 fail / 6 skipped, build exit 0, git diff --check clean.
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
2 participants
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.
What & why
ensureHive()currently mixes two responsibilities: ensuring the Hive structure exists and refreshing generated docs. That means ordinary runtime paths such aswriteTasks()andensureAgent()can unexpectedly overwritePROTOCOL.mdandCOMMANDS.md.This change makes runtime setup non destructive by creating those files only when missing, and moves explicit refresh behavior to the bootstrap path. It also adds generated notices and focused regressions so both the runtime preservation and bootstrap refresh contracts stay covered.
Closes ensureHive() rewrites PROTOCOL.md/COMMANDS.md outside bootstrap, and neither file is marked generated #451
Type of change
Evidence
Before
The same focused regression was run against the pre fix production implementation. Both ordinary runtime paths reproduced the overwrite behavior.
After
The generated doc lifecycle is now separated from ordinary Hive setup. Runtime operations preserve existing docs, while bootstrap still performs the explicit refresh.
How I tested it
node --test --test-name-pattern="writeTasks|ensureAgent" test/hive-generated-docs.test.cjsnode --test test/hive-generated-docs.test.cjsnpm run typechecknpm run buildgit diff --checknpm run test:focusedChecklist
npm run typecheckpasses.npm run test:focusedpasses.npm run buildsucceeds.commented-out code, or unrelated formatting churn in it.
DESIGN.md/tokens.ts— no ad-hoc colors,spacing, or fonts.
ATTRIBUTION.md.