story: fix autogeneration issues in relation to AI #203

New issue

Open

opened 2026-04-30 20:02:55 +00:00 by mik-tf · 0 comments

mik-tf commented

2026-04-30 20:02:55 +00:00

Owner

Symptom

Today on herodemo, the Contexts island showed "Root × 5" — every per-context query was silently falling back to the root context. The fix for this exact bug shipped months ago as hero_osis@7807258 (issue #41, MOCK_CONTEXTS expansion in hero_osis.rs).

Why is it back? Because crates/hero_osis_server/src/bin/hero_osis.rs is now auto-generated by build.rs (per-domain single-binary refactor). The file's own header literally says:

//! Auto-generated single-binary orchestrator for `hero_osis`.
//! DO NOT EDIT — regenerate via `cargo build` after schema or build.rs changes.

The codegen template did not include #41's expansion. So the next regeneration silently dropped the fix. Filed properly as lhumina_code/hero_osis#42.

The pattern

This is not unique to hero_osis. We have several auto-generated files across the workspace, and any time someone hand-applied a fix to one before it was added to the generator, the fix is a time bomb against the next regeneration.

Proposal

A one-time audit + ongoing rule:

Audit (one-time)

Find every file across the workspace that contains a "DO NOT EDIT" / "auto-generated" header. For each:

git log -p on the file → identify any commit that wasn't a regeneration (i.e. a commit that hand-edited the file).
For each such commit, check whether the change has been incorporated into the generator template.
If not → either re-apply at the generator layer (correct fix) or document why the manual fix is intentionally excluded.

Candidate files to audit (non-exhaustive):

hero_osis/crates/hero_osis_server/src/bin/hero_osis.rs — known case (#42).
All SDK files in hero_osis_sdk/ (auto-generated from OpenRPC).
All MCP tool registrations.
Auto-generated registry/island metadata.
Anything else with a // DO NOT EDIT header — grep -rn 'DO NOT EDIT' crates/ archipelagos/ bin/ will find them.

Ongoing rule

Document in CLAUDE.md:

Any fix or feature applied to a file with // DO NOT EDIT — auto-generated MUST be applied at the generator layer (build.rs, codegen template, OpenRPC schema) — never as a manual edit. Manual edits to generated files are invisible to the next regeneration and will silently disappear.

A linter check would be even better: a CI step that detects when an auto-generated file has been modified without a corresponding change in its generator. Future enhancement.

Acceptance

Inventory of all auto-generated files in the workspace + their generator paths, posted as a comment on this issue.
For each file, confirm no manual fixes are stranded (or file follow-up issues for any that are).
CLAUDE.md updated with the rule about manual edits to auto-generated files.
(Stretch) CI check: regenerate auto-generated files in CI and fail if they differ from committed version.

Cross-references

Discovered 2026-04-30 via lhumina_code/hero_osis#42 — same bug as hero_osis#41, silently re-introduced by codegen.
This is "architectural lesson worth filing as a separate convention" mentioned in the closing of hero_osis#42.

Signed-off-by: mik-tf

## Symptom Today on herodemo, the Contexts island showed "Root × 5" — every per-context query was silently falling back to the root context. The fix for this exact bug shipped months ago as `hero_osis@7807258` (issue [#41](https://forge.ourworld.tf/lhumina_code/hero_osis/issues/41), MOCK_CONTEXTS expansion in `hero_osis.rs`). Why is it back? Because `crates/hero_osis_server/src/bin/hero_osis.rs` is now auto-generated by `build.rs` (per-domain single-binary refactor). The file's own header literally says: ```rust //! Auto-generated single-binary orchestrator for `hero_osis`. //! DO NOT EDIT — regenerate via `cargo build` after schema or build.rs changes. ``` The codegen template did not include #41's expansion. So the next regeneration silently dropped the fix. Filed properly as https://forge.ourworld.tf/lhumina_code/hero_osis/issues/42. ## The pattern This is not unique to hero_osis. We have several auto-generated files across the workspace, and any time someone hand-applied a fix to one before it was added to the generator, the fix is a time bomb against the next regeneration. ## Proposal A one-time audit + ongoing rule: ### Audit (one-time) Find every file across the workspace that contains a "DO NOT EDIT" / "auto-generated" header. For each: 1. `git log -p` on the file → identify any commit that wasn't a regeneration (i.e. a commit that hand-edited the file). 2. For each such commit, check whether the change has been incorporated into the generator template. 3. If not → either re-apply at the generator layer (correct fix) or document why the manual fix is intentionally excluded. Candidate files to audit (non-exhaustive): - `hero_osis/crates/hero_osis_server/src/bin/hero_osis.rs` — known case (#42). - All SDK files in `hero_osis_sdk/` (auto-generated from OpenRPC). - All MCP tool registrations. - Auto-generated registry/island metadata. - Anything else with a `// DO NOT EDIT` header — `grep -rn 'DO NOT EDIT' crates/ archipelagos/ bin/` will find them. ### Ongoing rule Document in CLAUDE.md: > Any fix or feature applied to a file with `// DO NOT EDIT — auto-generated` MUST be applied at the generator layer (build.rs, codegen template, OpenRPC schema) — never as a manual edit. Manual edits to generated files are invisible to the next regeneration and will silently disappear. A linter check would be even better: a CI step that detects when an auto-generated file has been modified without a corresponding change in its generator. Future enhancement. ## Acceptance - [ ] Inventory of all auto-generated files in the workspace + their generator paths, posted as a comment on this issue. - [ ] For each file, confirm no manual fixes are stranded (or file follow-up issues for any that are). - [ ] CLAUDE.md updated with the rule about manual edits to auto-generated files. - [ ] (Stretch) CI check: regenerate auto-generated files in CI and fail if they differ from committed version. ## Cross-references - Discovered 2026-04-30 via https://forge.ourworld.tf/lhumina_code/hero_osis/issues/42 — same bug as hero_osis#41, silently re-introduced by codegen. - This is "architectural lesson worth filing as a separate convention" mentioned in the closing of hero_osis#42. Signed-off-by: mik-tf

mik-tf self-assigned this

2026-04-30 20:02:55 +00:00

mik-tf referenced this issue from lhumina_code/hero_osis

2026-04-30 20:11:59 +00:00

[arch] hero_osis: contexts as data, strict resolution, drop auto-generated single-bin #43

mik-tf referenced this issue from lhumina_code/hero_demo

2026-04-30 23:01:22 +00:00

[goal] Killer demo capabilities — what hero_demo should be able to demonstrate #51

mik-tf referenced this issue from lhumina_code/hero_demo

2026-05-01 02:05:19 +00:00

[vision] Hero OS as an ambient AI desktop — sovereign, voice-native, multi-context #52

mik-tf referenced this issue from lhumina_code/hero_agent

2026-05-02 01:17:43 +00:00

[arch] Curated MCP tool surface + semantic discovery via embedder/indexer (stop the brute-force) #15

despiegk changed title from ~~[infra] Audit auto-generated files for stranded manual fixes (codegen drift)~~ to story: fix autogeneration issues in relation to AI

2026-05-05 04:11:22 +00:00

mik-tf referenced this issue from lhumina_code/hero_osis

2026-05-06 15:47:36 +00:00

ci: rename release artifacts to target-triple shape (home#212) #45