# 07 — Gaps and Open Questions --- ## 1. Must be written fresh | # | Page | Why | |---|---|---| | **G1** | **`/lite/`** | The commissioning priority. The specification exists but lives in §7 of an 8,229-word manual about *email*, in a different repository. No agent will find it there | | **G2** | **`/shipped/`** | Nothing in the corpus tells you what is installable. Four packages on PyPI, two of them empty, four unpublished — and no document says so | | **G3** | **`/dsl/`** | The `.issues` flat-file DSL is built, tested and in live use with **zero prose documentation anywhere** | | **G4** | **A five-minute lite worked example** | Three tasks, one blocked, one closed, actual commands. The corpus has the protocol but no walkthrough | | **G5** | **`/shipped/corrections.html`** | The README claims that need correcting — §2 of `06` | | **G6** | **The lite→full upgrade path** | What happens when a lite graph outgrows lite? **There is no converter today.** State it rather than implying one | --- ## 2. Documented but not built Publish these as *argued design*, clearly labelled — several are genuinely good ideas. | Claimed | Where | Reality | |---|---|---| | `issues-fs-lexicon` — *"required by every Issues-FS repository"* | lexicon v1 + v2, **~7,000 words** | No repo, no package, in no `pyproject.toml`. **The most-theorised, least-built idea in the corpus** | | `Issues-FS__Service__Client__JS` (npm `issues-fs-client`) | architecture overview | No repo, no npm package | | `Issues-FS__Service__GitHub` / `__S3` / `__Jira` | architecture overview | No repos | | `issues-fs-github-backup` — *"3-command path to value"* | use-case worked example (2,549 w) | Does not exist | | Git Repository Reader Service | dev-brief (2,935 w) | No code | | Type-Safe Properties System | dev-brief (2,734 w) | `Schema__Node.properties` is still `Dict[str, Any]`; `Enum__Property__Type` has **zero references** | | S3 storage backend | 4 documents | Enum has MEMORY/LOCAL_DISK/SQLITE/ZIP | | MGraph-DB integration | 3 documents | Zero imports, zero dependency entries | | `.issues/indexes/issues.mgraph.json` | `Issues-FS/README.md` storage block | No code writes it | | `config/settings.json` | `Path__Handler__Graph_Node.path_for_settings()` | The path method exists; nothing reads or writes the file | --- ## 3. Open questions worth publishing unresolved Following the pki.sgit.ai convention of numbering open questions in public. | # | Question | Where the corpus gets closest | |---|---|---| | **Q1** | Is the lexicon still the plan, or is it superseded? | ~7,000 words argue for it as a hard dependency; nothing has been built in six months | | **Q2** | Which on-disk layout is canonical — hierarchical `issues/`, flat `data/`, or mixed? | Three are in live use and the docs describe a fourth. The CLI produces one of them | | **Q3** | Should `_index.json` exist at all? | It is stale wherever it exists, and the largest, healthiest graph has none | | **Q4** | Does `relates-to`/`relates-to` stay? | It ships in `link-types.json` and one live edge uses it; the wider corpus calls it meaningless | | **Q5** | Is the service a real target, or should the two empty wheels be yanked? | Six commits each, all on one day in February, nothing since | | **Q6** | What is the lite→full upgrade path? | Not addressed anywhere | | **Q7** | Why does the core library depend on its own CLI? | `issues-fs` lists `issues-fs-cli` in `pyproject.toml` — a circular dependency nobody has explained | --- ## 4. Honest tensions 1. **The ecosystem is bigger than what ships.** Eight packages, four published, two of those empty. The repo count implies a platform; the wheel contents imply a library and a CLI. Both readings are fair — say which one you are offering. 2. **Every README is behind the code.** Version, test counts, submodule counts, role counts, backend list, integrations. The code is in better shape than its documentation, which is an unusual and reassuring failure mode — but it means **no README can be republished unedited.** 3. **The philosophy has outgrown the implementation.** The concept documents are now the foundation of another site and a published book, while `issues-fs-lexicon` — their central architectural claim — was never built. 4. **Self-referential is a strong claim to make carefully.** *"The issue tracker tracks its own development"* is true for three repos and false for three others, whose `.issues/` folders contain only config scaffolding. 5. **Three agent surfaces, one documented.** Lite is specified elsewhere; the DSL is undocumented; only `--for-agent` is discoverable. **That gap is this site's biggest opportunity.** 6. **Apache 2.0 with no named copyright holder** is a real defect, not a formality, and it sits under nine repos and four PyPI packages. --- ## 5. Fixes worth doing at source, alongside the site 1. **Merge `Issues-FS__Docs` `dev` → `main`.** Its `main` is still `Initial commit`, 24 commits behind, which is why `pip install issues-fs-docs` 404s while the README shows a PyPI badge. 2. **Name the copyright holder** in all nine `LICENSE` files; add a `NOTICE`. 3. **Decide the CC BY question** and make it real in `Issues-FS__Docs`, or drop the claim from `Issues-FS__Dev/README.md`. 4. **Yank or fill the two empty wheels.** Their PyPI summaries currently describe code that is not in them. 5. **Mark the superseded lexicon v1** — it sits in `already-legacy/` with no marker in the file. 6. **Correct the four false claims** (S3, MGraph-DB, lexicon, version/test counts) in the READMEs, so the site and the repos agree. 7. **Add the Designer role** to the role table — it is the 11th submodule and appears in no document. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).