chore: clean up specs/ — drop stale planning docs, keep runtime artefacts #110

Merged

mahmoud merged 2 commits from development_specs_cleanup into development

2026-04-28 05:40:54 +00:00

mahmoud commented

2026-04-27 17:36:19 +00:00

Owner

Summary

Drops eight stale pre-implementation planning docs from specs/ that duplicate the canonical docs/ content (and in places contradict the current implementation — e.g. specs/startup_flow.md still talks about binding a TCP listener; we've been Unix-socket-only for a while).

Deleted

File	Why
`specs/architecture.md`	Now in `docs/architecture.md` (more current).
`specs/components.md`	Module breakdown, duplicated by `docs/architecture.md`.
`specs/concepts.md`	Now in `docs/concepts.md`.
`specs/dataflows.md`	Covered by the Data Flow section of `docs/architecture.md`.
`specs/doctree_ai_metadata.md`	Spec for a feature that's already implemented in `crates/hero_books_lib/src/doctree/ai.rs`.
`specs/DOCTREE.md`	Now in `docs/doctree.md`.
`specs/startup_flow.md`	TCP-era; `docs/server.md` is canonical.
`specs/vector_cache.md`	Covered by `docs/search.md` and `docs/ai_processing.md`.

3,112 lines removed; nothing the runtime touches.

Kept

specs/ontologies/ — these .toml files are runtime artefacts. They're embedded into hero_books_lib at compile time via include_str!("../../specs/ontologies/ontology_*.toml") in crates/hero_books_lib/src/ontology/embedded.rs. They can't move without code changes.
specs/schemas/ — canonical OSchema definitions for publishing types (book, site, page, navigation, ontology) and the webservice API. Not loaded at build or runtime today, but kept as schema reference material.

Added

A small specs/README.md so anyone who navigates into the directory knows what survived and where the real docs live (docs/).

Test plan

grep -rn "specs/" --include="*.rs" confirms only specs/ontologies/ is referenced from Rust source — nothing depends on the deleted .md files.
cargo check --workspace (implicit — no code paths changed)
Manual review of specs/README.md in the file viewer.

🤖 Generated with Claude Code

## Summary Drops eight stale pre-implementation planning docs from `specs/` that duplicate the canonical `docs/` content (and in places contradict the current implementation — e.g. `specs/startup_flow.md` still talks about binding a TCP listener; we've been Unix-socket-only for a while). ### Deleted | File | Why | |---|---| | `specs/architecture.md` | Now in `docs/architecture.md` (more current). | | `specs/components.md` | Module breakdown, duplicated by `docs/architecture.md`. | | `specs/concepts.md` | Now in `docs/concepts.md`. | | `specs/dataflows.md` | Covered by the Data Flow section of `docs/architecture.md`. | | `specs/doctree_ai_metadata.md` | Spec for a feature that's already implemented in `crates/hero_books_lib/src/doctree/ai.rs`. | | `specs/DOCTREE.md` | Now in `docs/doctree.md`. | | `specs/startup_flow.md` | TCP-era; `docs/server.md` is canonical. | | `specs/vector_cache.md` | Covered by `docs/search.md` and `docs/ai_processing.md`. | 3,112 lines removed; nothing the runtime touches. ### Kept - **`specs/ontologies/`** — these `.toml` files are runtime artefacts. They're embedded into `hero_books_lib` at compile time via `include_str!("../../specs/ontologies/ontology_*.toml")` in [`crates/hero_books_lib/src/ontology/embedded.rs`](https://forge.ourworld.tf/lhumina_code/hero_books/src/branch/development/crates/hero_books_lib/src/ontology/embedded.rs). They can't move without code changes. - **`specs/schemas/`** — canonical OSchema definitions for publishing types (book, site, page, navigation, ontology) and the webservice API. Not loaded at build or runtime today, but kept as schema reference material. ### Added A small `specs/README.md` so anyone who navigates into the directory knows what survived and where the real docs live (`docs/`). ## Test plan - [x] `grep -rn "specs/" --include="*.rs"` confirms only `specs/ontologies/` is referenced from Rust source — nothing depends on the deleted `.md` files. - [x] `cargo check --workspace` (implicit — no code paths changed) - [ ] Manual review of `specs/README.md` in the file viewer. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

mahmoud added 1 commit

2026-04-27 17:36:19 +00:00

chore: clean up specs/ — drop stale planning docs, keep runtime artifacts

Test / test (pull_request) Successful in 6m47s

Details

Test / integration (pull_request) Has been cancelled

Details

889963562d

The eight pre-implementation planning .md files duplicated material now in
docs/ and contained TCP-era examples that no longer match the Unix-socket-
only implementation (e.g. specs/startup_flow.md still talks about binding
a TCP listener and listed the embedder under http://localhost:3752/rpc).

Deleted:
- specs/architecture.md       (now docs/architecture.md, more current)
- specs/components.md         (module breakdown, duplicated by architecture)
- specs/concepts.md           (now docs/concepts.md)
- specs/dataflows.md          (now in docs/architecture.md "Data Flow")
- specs/doctree_ai_metadata.md (spec for an already-implemented feature)
- specs/DOCTREE.md            (now docs/doctree.md)
- specs/startup_flow.md       (TCP-era; current docs/server.md is canonical)
- specs/vector_cache.md       (covered by docs/search.md / ai_processing.md)

Kept:
- specs/ontologies/  — runtime artefacts; embedded into hero_books_lib via
                       include_str! in crates/hero_books_lib/src/ontology/
                       embedded.rs. Cannot move without code changes.
- specs/schemas/     — canonical OSchema definitions for publishing types
                       and the webservice API. Reference material; not
                       loaded at build or runtime today.

Added specs/README.md so anyone who wanders in knows what survived and
where the actual docs live (docs/).

mahmoud added 1 commit

2026-04-27 18:48:22 +00:00