coilyco-gaming/galaxy-gen

Watch

The #46 grandfathering is still in place: all 25 excludes are load-bearing #78

New issue

Open

opened 2026-08-12 09:38:46 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-12 09:38:46 +00:00

Member

Context

#46 closed on 2026-08-06 with this done-condition:

ward exec precommit passes without documentation-layout or code-comments grandfathering for tracked source files.

That condition is not met. pyproject.toml still carries 25 exclude entries, and none of them is dead.

Measured, 2026-08-12

Each entry was removed individually against the real config and the suite re-run. Every single removal turns the suite red, so nothing here is leftover.

[tool.agentic-os.code-comments] - 9 entries, in rough size order:

src/rust/galaxy.rs - several hundred over-long comment blocks, by far the bulk
src/js/lib/dataviz.tsx - roughly 150
src/js/lib/application.tsx, src/js/lib/tick-worker.ts, src/js/lib/galaxy.ts
src/rust/events.rs, src/rust/process.rs, src/rust/stars.rs
playwright.config.ts
also .github/workflows/action.yml, .github/workflows/trufflehog.yml, .pre-commit-config.yaml, .agents/skills/categories.yaml - each 1 violation

[tool.agentic-os.documentation-layout] - the load-bearing ones:

docs/galaxy-rust.md, docs/processes-events.md - both still over the caps, and both named in #46 as the split work
development.md - fails the root-Markdown-filename rule, not a size cap. Clearing it means moving the file under docs/ and updating every reference, including AGENTS.md and README.md
the 7 .agents/skills/* docs - 87 to 129 lines each, all well over the char cap
pkg/** - generated wasm-pack output. This one should stay, and #46 agreed

[tool.agentic-os.dead-cross-links] - pkg/**, same reason, stays.

A method warning

An earlier pass concluded 13 of these were dead. That was wrong, and the mistake is worth recording: deleting an entire [tool.agentic-os.*] table makes the validator fall back to different defaults than removing individual entries from a live table. Test one entry at a time against the real config, or the result is an artifact of the method.

Suggested order

docs/galaxy-rust.md and docs/processes-events.md splits - cheap, and the original #46 scope
The 7 .agents/skills/* docs - mechanical
development.md move under docs/ - small diff, wide reference update
src/js/lib/dataviz.tsx, then src/rust/galaxy.rs - the real project, a large diff through the simulation core, and worth its own change rather than being bundled

Keep pkg/** excluded in both hooks.

Done when

Every entry except pkg/** is gone from pyproject.toml and ward exec precommit is green.

Note

The suite is currently green with the excludes in place, so this is not blocking anyone. It was surfaced while bumping the hook pin to aos-precommit-v0.18.0 and clearing the violations that were blocking every commit in this repo.

## Context #46 closed on 2026-08-06 with this done-condition: > `ward exec precommit` passes without documentation-layout or code-comments grandfathering for tracked source files. That condition is not met. `pyproject.toml` still carries 25 exclude entries, and none of them is dead. ## Measured, 2026-08-12 Each entry was removed individually against the real config and the suite re-run. Every single removal turns the suite red, so nothing here is leftover. `[tool.agentic-os.code-comments]` - 9 entries, in rough size order: * `src/rust/galaxy.rs` - several hundred over-long comment blocks, by far the bulk * `src/js/lib/dataviz.tsx` - roughly 150 * `src/js/lib/application.tsx`, `src/js/lib/tick-worker.ts`, `src/js/lib/galaxy.ts` * `src/rust/events.rs`, `src/rust/process.rs`, `src/rust/stars.rs` * `playwright.config.ts` * also `.github/workflows/action.yml`, `.github/workflows/trufflehog.yml`, `.pre-commit-config.yaml`, `.agents/skills/categories.yaml` - each 1 violation `[tool.agentic-os.documentation-layout]` - the load-bearing ones: * `docs/galaxy-rust.md`, `docs/processes-events.md` - both still over the caps, and both named in #46 as the split work * `development.md` - fails the root-Markdown-filename rule, not a size cap. Clearing it means moving the file under `docs/` and updating every reference, including `AGENTS.md` and `README.md` * the 7 `.agents/skills/*` docs - 87 to 129 lines each, all well over the char cap * `pkg/**` - generated wasm-pack output. This one should stay, and #46 agreed `[tool.agentic-os.dead-cross-links]` - `pkg/**`, same reason, stays. ## A method warning An earlier pass concluded 13 of these were dead. That was wrong, and the mistake is worth recording: deleting an entire `[tool.agentic-os.*]` table makes the validator fall back to different defaults than removing individual entries from a live table. Test one entry at a time against the real config, or the result is an artifact of the method. ## Suggested order 1. `docs/galaxy-rust.md` and `docs/processes-events.md` splits - cheap, and the original #46 scope 2. The 7 `.agents/skills/*` docs - mechanical 3. `development.md` move under `docs/` - small diff, wide reference update 4. `src/js/lib/dataviz.tsx`, then `src/rust/galaxy.rs` - the real project, a large diff through the simulation core, and worth its own change rather than being bundled Keep `pkg/**` excluded in both hooks. ## Done when Every entry except `pkg/**` is gone from `pyproject.toml` and `ward exec precommit` is green. ## Note The suite is currently green with the excludes in place, so this is not blocking anyone. It was surfaced while bumping the hook pin to `aos-precommit-v0.18.0` and clearing the violations that were blocking every commit in this repo.

coilyco-ops referenced this issue

2026-08-14 02:56:56 +00:00

Clear ten of the #78 grandfathering entries: the doc splits, the development.md move, and every small comment block #82

coilyco-ops referenced this issue from a commit

2026-08-14 02:57:24 +00:00

docs: split the oversized docs and clear ten grandfathered excludes

coilyco-ops commented

2026-08-14 02:57:59 +00:00

Author

Member

Ten cleared in #82; the remaining fifteen are two different things, and only one of them is debt

Measured against the live config, one entry at a time, per the method warning above.

Cleared (#82, commit `42ad68f`)

development.md (both config files), docs/galaxy-rust.md, docs/processes-events.md, and seven of the nine code-comments entries: application.tsx, galaxy.ts, tick-worker.ts, events.rs, stars.rs, process.rs, playwright.config.ts.

Still real work: two files, 184 blocks

Recounted against the current hook - it is fewer than the issue estimates, because each over-long block emits one FAIL per excess line:

file	over-long blocks	longest	of which 3-line
`src/rust/galaxy.rs`	139	22	59
`src/js/lib/dataviz.tsx`	45	14	17

The 76 three-line blocks are a line each. The remaining 108 are 4-22 lines of physics and optimization rationale, and the rule's own remedy - move the explanation to docs/ - is the right one but is authorship, not reflowing. Agreed with the issue that this is its own change.

Not debt: seven skill docs

tooling-skill-authoring/SKILL.md line 71, this repo's own authority on the question:

SKILL.md is hard-capped at 500 lines and 10 KB by the validator. Past either, the harness loader degrades. Push detail into references/<topic>.md under the same skill directory if a SKILL.md is filling up. Reference files are not capped.

So two validators disagree about .agents/skills/**. skill-conventions says 500 lines / 10 KB for SKILL.md and no cap on references; documentation-layout says 80 lines / 4000 chars for every Markdown file. Under the second, every skill in the ecosystem is illegal, and the four reference files here (4.4-13.3 KB) are illegal by a rule their own spec says does not apply to them.

Splitting them to satisfy that cap would be an artifact of the method in exactly the way this issue warns about. The fix is upstream - documentation-layout should not walk .agents/skills/** - and these seven entries are the correct local resolution until it does. Recommend keeping them with that rationale recorded in pyproject.toml.

Not debt: the four YAML entries

They look like duplicates of the same paths in .agentic-os.toml, which carries a written rationale (galaxy-gen#24: operational YAML whose inline comments explain the key they sit beside). Removing them anyway turns the suite red - 13 violations in categories.yaml, 4 in action.yml, 3 in .pre-commit-config.yaml, 1 in trufflehog.yml. The two files do not merge the way the duplication suggests, so these are load-bearing copies of a justified exclusion, not leftovers.

Judgment call: `docs/perf-rewrite.md`

Not enumerated in the issue body but present in the excludes, and now ~1800 lines across four parts. No split satisfies a 4000-char cap without shredding a chronological engineering journal into roughly 25 fragments - splitting by part still leaves four files of 10-15 KB each. Worth an explicit decision rather than inheriting it.

Suggested revision to "done when"

Every entry except pkg/**, the seven skill docs, the four YAML entries, and docs/perf-rewrite.md is gone, and each survivor carries its rationale inline. That leaves galaxy.rs and dataviz.tsx as the whole of the remaining work here.

## Ten cleared in #82; the remaining fifteen are two different things, and only one of them is debt Measured against the live config, one entry at a time, per the method warning above. ### Cleared (#82, commit `42ad68f`) `development.md` (both config files), `docs/galaxy-rust.md`, `docs/processes-events.md`, and seven of the nine code-comments entries: `application.tsx`, `galaxy.ts`, `tick-worker.ts`, `events.rs`, `stars.rs`, `process.rs`, `playwright.config.ts`. ### Still real work: two files, 184 blocks Recounted against the current hook - it is fewer than the issue estimates, because each over-long block emits one FAIL per excess line: | file | over-long blocks | longest | of which 3-line | |---|---:|---:|---:| | `src/rust/galaxy.rs` | 139 | 22 | 59 | | `src/js/lib/dataviz.tsx` | 45 | 14 | 17 | The 76 three-line blocks are a line each. The remaining 108 are 4-22 lines of physics and optimization rationale, and the rule's own remedy - move the explanation to `docs/` - is the right one but is authorship, not reflowing. Agreed with the issue that this is its own change. ### Not debt: seven skill docs `tooling-skill-authoring/SKILL.md` line 71, this repo's own authority on the question: > `SKILL.md` is hard-capped at 500 lines and 10 KB by the validator. Past either, the harness loader degrades. Push detail into `references/<topic>.md` under the same skill directory if a SKILL.md is filling up. **Reference files are not capped.** So two validators disagree about `.agents/skills/**`. `skill-conventions` says 500 lines / 10 KB for `SKILL.md` and no cap on references; `documentation-layout` says 80 lines / 4000 chars for every Markdown file. Under the second, every skill in the ecosystem is illegal, and the four reference files here (4.4-13.3 KB) are illegal by a rule their own spec says does not apply to them. Splitting them to satisfy that cap would be an artifact of the method in exactly the way this issue warns about. The fix is upstream - `documentation-layout` should not walk `.agents/skills/**` - and these seven entries are the correct local resolution until it does. Recommend keeping them with that rationale recorded in `pyproject.toml`. ### Not debt: the four YAML entries They look like duplicates of the same paths in `.agentic-os.toml`, which carries a written rationale (galaxy-gen#24: operational YAML whose inline comments explain the key they sit beside). Removing them anyway turns the suite red - 13 violations in `categories.yaml`, 4 in `action.yml`, 3 in `.pre-commit-config.yaml`, 1 in `trufflehog.yml`. The two files do not merge the way the duplication suggests, so these are load-bearing copies of a justified exclusion, not leftovers. ### Judgment call: `docs/perf-rewrite.md` Not enumerated in the issue body but present in the excludes, and now ~1800 lines across four parts. No split satisfies a 4000-char cap without shredding a chronological engineering journal into roughly 25 fragments - splitting by part still leaves four files of 10-15 KB each. Worth an explicit decision rather than inheriting it. ### Suggested revision to "done when" Every entry except `pkg/**`, the seven skill docs, the four YAML entries, and `docs/perf-rewrite.md` is gone, and each survivor carries its rationale inline. That leaves `galaxy.rs` and `dataviz.tsx` as the whole of the remaining work here.

coilyco-ops referenced this issue

2026-08-14 03:04:07 +00:00

Clear the dataviz.tsx comment grandfathering: 45 blocks, and the renderer's reasoning becomes three docs #83

coilyco-ops commented

2026-08-14 03:05:40 +00:00

Author

Member

dataviz.tsx cleared in #83. galaxy.rs is a different kind of file, and I stopped rather than do it blind.

dataviz.tsx went fine, because its 45 blocks are descriptive - they say what a pass does, and the reasoning behind them relocated cleanly into three rendering docs. galaxy.rs is not that. Its 139 blocks are 730 comment lines, and I read all twenty of the 8+ line ones and sampled the 59 three-line ones before deciding.

What is actually in them

They are overwhelmingly guardrails sitting on the exact line where the mistake would be made, and measurement provenance for a result that was already retracted once:

/// Measured caveat, see galaxy-gen#66: ASSOCIATION_ORBIT_SPEED_CAP
/// is an absolute speed and it binds on nearly every birth, which
/// hands newborns 2.0-3.2x the local circular speed ... Do
/// not "fix" this in isolation; #66 has the numbers.

/// CAVEAT (galaxy-gen#66): this does not distinguish a circular disk
/// orbit from an eccentric orbit at pericenter ... Do not tune against it.

/// Calibration for `rotation_dispersion_ratio` against two populations
/// whose answer is known by construction, because a metric nobody has
/// checked against a known answer is how galaxy-gen#66 went wrong the
/// first time.

And the pattern holds all the way down to the three-line blocks - each is a claim plus the failure mode it prevents:

/// Flat-rotation-curve speed of the static halo potential. The halo
/// stands in for dark matter: gas self-gravity alone cannot hold a
/// flat curve, and without one the disk either freezes or falls in.

Why relocating these is worse than leaving them

The entire value of these particular comments is locality. "Do not fix this in isolation" works because it is attached to the constant someone is about to fix. Replaced with // see docs/x.md, it becomes a link that the person mid-edit does not follow, and the mistake it exists to prevent gets easier to make - which is the opposite of what a comment-discipline rule is for. CONFINE_STIFFNESS alone carries a reverted experiment, four broken tests, and the reason the cheap fix was chosen; that is not prose that wants a doc, it is a fence around a specific line.

It is also all-or-nothing: the exclude only lifts when every block in the file conforms, so there is no partial version of this that removes the entry.

Recommendation

Keep src/rust/galaxy.rs excluded, with that rationale recorded inline in pyproject.toml the way .agentic-os.toml records the YAML one. That makes it a documented exception rather than inherited debt, which is what this issue is really asking for.

The alternative, if you want it anyway

It is roughly an hour: ~450 lines of rationale into five or six new docs (gravity-kernel.md, integrator.md, star-metrics.md, seeding-internals.md, test-calibration.md), and 139 comments compressed to two lines plus a pointer. Mechanically safe - comments only, no behavior change, the golden tests would prove it. Say the word and I will do it. I did not want to reshape the character of the file the coding-rust skill holds up as the model without you choosing that deliberately.

Where #78 stands

entry	state
`development.md`, `galaxy-rust.md`, `processes-events.md`	cleared, #82
7 small code-comments files	cleared, #82
`dataviz.tsx`	cleared, #83
`src/rust/galaxy.rs`	your call - recommend keep, rationale above
7 `.agents/skills/*` docs	recommend keep - validator conflict, previous comment
4 YAML entries	recommend keep - measured load-bearing, previous comment
`docs/perf-rewrite.md`	recommend keep - no split satisfies the cap
`pkg/**`	keep, agreed in #46

Eleven of twenty-five cleared, and every survivor has a measured reason rather than an inherited one.

## dataviz.tsx cleared in #83. galaxy.rs is a different kind of file, and I stopped rather than do it blind. `dataviz.tsx` went fine, because its 45 blocks are descriptive - they say what a pass does, and the reasoning behind them relocated cleanly into three rendering docs. `galaxy.rs` is not that. Its 139 blocks are 730 comment lines, and I read all twenty of the 8+ line ones and sampled the 59 three-line ones before deciding. ### What is actually in them They are overwhelmingly **guardrails sitting on the exact line where the mistake would be made**, and measurement provenance for a result that was already retracted once: ```rust /// Measured caveat, see galaxy-gen#66: ASSOCIATION_ORBIT_SPEED_CAP /// is an absolute speed and it binds on nearly every birth, which /// hands newborns 2.0-3.2x the local circular speed ... Do /// not "fix" this in isolation; #66 has the numbers. ``` ```rust /// CAVEAT (galaxy-gen#66): this does not distinguish a circular disk /// orbit from an eccentric orbit at pericenter ... Do not tune against it. ``` ```rust /// Calibration for `rotation_dispersion_ratio` against two populations /// whose answer is known by construction, because a metric nobody has /// checked against a known answer is how galaxy-gen#66 went wrong the /// first time. ``` And the pattern holds all the way down to the three-line blocks - each is a claim plus the failure mode it prevents: ```rust /// Flat-rotation-curve speed of the static halo potential. The halo /// stands in for dark matter: gas self-gravity alone cannot hold a /// flat curve, and without one the disk either freezes or falls in. ``` ### Why relocating these is worse than leaving them The entire value of these particular comments is **locality**. "Do not fix this in isolation" works because it is attached to the constant someone is about to fix. Replaced with `// see docs/x.md`, it becomes a link that the person mid-edit does not follow, and the mistake it exists to prevent gets easier to make - which is the opposite of what a comment-discipline rule is for. `CONFINE_STIFFNESS` alone carries a reverted experiment, four broken tests, and the reason the cheap fix was chosen; that is not prose that wants a doc, it is a fence around a specific line. It is also all-or-nothing: the exclude only lifts when every block in the file conforms, so there is no partial version of this that removes the entry. ### Recommendation Keep `src/rust/galaxy.rs` excluded, with that rationale recorded inline in `pyproject.toml` the way `.agentic-os.toml` records the YAML one. That makes it a documented exception rather than inherited debt, which is what this issue is really asking for. ### The alternative, if you want it anyway It is roughly an hour: ~450 lines of rationale into five or six new docs (`gravity-kernel.md`, `integrator.md`, `star-metrics.md`, `seeding-internals.md`, `test-calibration.md`), and 139 comments compressed to two lines plus a pointer. Mechanically safe - comments only, no behavior change, the golden tests would prove it. Say the word and I will do it. I did not want to reshape the character of the file the `coding-rust` skill holds up as the model without you choosing that deliberately. ### Where #78 stands | entry | state | |---|---| | `development.md`, `galaxy-rust.md`, `processes-events.md` | cleared, #82 | | 7 small code-comments files | cleared, #82 | | `dataviz.tsx` | cleared, #83 | | `src/rust/galaxy.rs` | **your call** - recommend keep, rationale above | | 7 `.agents/skills/*` docs | recommend keep - validator conflict, previous comment | | 4 YAML entries | recommend keep - measured load-bearing, previous comment | | `docs/perf-rewrite.md` | recommend keep - no split satisfies the cap | | `pkg/**` | keep, agreed in #46 | Eleven of twenty-five cleared, and every survivor has a measured reason rather than an inherited one.

coilyco-ops referenced this issue

2026-08-14 05:00:05 +00:00

Land #70: give stars orbits their own potential holds, and clear the last galaxy.rs grandfathering #85

coilyco-ops added the

labels

2026-08-15 21:07:47 +00:00