# issues-fs.sgit.ai — Brief Pack

**Pack version:** v1.0 · 22 August 2026
**Target site:** `issues-fs.sgit.ai`
**Primary sources:** [`owasp-sbot/Issues-FS__Docs`](https://github.com/owasp-sbot/Issues-FS__Docs) · [`owasp-sbot/Issues-FS__Dev`](https://github.com/owasp-sbot/Issues-FS__Dev) (19 submodules) · six module repos · [`SGraph-AI__App__Send`](https://github.com/the-cyber-boardroom/SGraph-AI__App__Send) @ v0.33.62 (the flagship consumer)
**Siblings:** sgit.ai · nhi.sgit.ai · pki.sgit.ai · graphs.sgit.ai (v0.3.9) · sg-sentinel.sgit.ai · newsroom.sgit.ai (in build)

---

## 0. What this site is for

Two jobs, and the second is the one most project sites get wrong.

**Job 1 — teach the key concepts.** Issues-FS is the origin of the graph philosophy the whole estate now runs on. `thinking-in-graphs.md` was written here on **5 February 2026** and only reached SGraph Send four months later. graphs.sgit.ai is built on it. This site is its home.

**Job 2 — let a visitor navigate what already exists and has shipped.** Which packages are on PyPI, at what version, what they actually do, what to install, and what the commands are. This is the job the corpus currently cannot do for itself: **every README in the ecosystem is stale**, and two published PyPI packages are empty shells whose descriptions promise code that is not in the wheel.

And a third, called out explicitly in the commissioning brief:

**Job 3 — document Issues-FS-lite properly.** The mode designed for agents working directly on a filesystem, with no binary. It is the most immediately usable thing in the ecosystem and it currently **has no home document** — see §3.

---

## 1. What actually ships — verified against live PyPI

This table is the site's most valuable single asset. Nothing like it exists anywhere today.

| PyPI package | On PyPI | Latest | Repo version | Reality |
|---|---|---|---|---|
| **`issues-fs`** | ✅ | **0.7.0** | v0.7.1 (dev) | **Real.** 103-file wheel, 98 source files, 5,401 LOC, **604 tests** |
| **`issues-fs-cli`** | ✅ | **0.3.0** | v0.3.0 | **Real.** 23-file wheel, 14 commands, **94 tests**. The most credible end-user surface |
| `issues-fs-service` | ✅ | 0.2.0 | v0.2.0 | ⚠️ **Empty shell.** 8-file wheel, no FastAPI code, no routes. PyPI summary says *"FastAPI server with REST endpoints"* |
| `issues-fs-service-client-python` | ✅ | 0.2.0 | v0.2.0 | ⚠️ **Empty shell.** 8-file wheel, no client, no schemas. Summary says *"API schemas and Python client"* |
| `issues-fs-service-ui` | ❌ 404 | — | v0.2.1 | 142 files in repo, unpublished |
| `issues-fs-docs` | ❌ 404 | — | v0.1.6 | README shows a `pip install` and a PyPI badge that 404 |
| `issues-fs-dev` | ❌ 404 | — | v0.3.2 | — |
| `issues-fs-dev-utils` | ❌ 404 | — | v0.1.1 | 535 LOC, 19 tests, good user guide, absent from every ecosystem map |

**Why:** CI publishes to PyPI only from `main`. Seven of eight repos sit on `dev` well ahead of `main`. **`Issues-FS__Docs`'s `main` is still at `Initial commit`, 24 commits behind `dev`** — which is why the docs package 404s.

**The honest headline for `/shipped/`:** *"Two packages are real and installable. Two are published but empty. Four are not published at all. Here is the line."*

---

## 2. The one-paragraph thesis

Issues-FS is a git-native issue tracker where **the issues are files and the files are a graph**. A node is a JSON file on disk; an edge is a typed verb stored on both endpoints; the folder hierarchy is the containment structure. Nothing runs — no server, no daemon, no database is required — so the tracker lives inside the repository it tracks, versions with it, branches with it, and can be read by `cat`, `grep` and `find`. That makes it legible to a human, diffable by git, and directly operable by an agent. The philosophy underneath is that **a node has no inherent meaning; meaning is discovered through the edges you can trace from it** — which is why the type system is a graph of typed relationships rather than a schema of fields.

---

## 3. Issues-FS-lite — the priority, and the problem

**The commissioning brief calls this "very important". It is, and it is currently homeless.**

Issues-FS-lite is the mode for agents operating directly on a filesystem **without the `issues-fs` binary**: four `mv` operations, markdown files with YAML front-matter, three folders. No Python, no install, no CLI.

**Where the specification actually lives:** §7 of `team/humans/dinis_cruz/briefs/05/06/email-fs-lite-v0.6.md` — **in the SGraph Send repo**, inside an 8,229-word manual about *email*. The Librarian's own reality file records the situation exactly:

> *"Issues-FS-lite specification | **EXISTS (specification only)** — embedded in Email-FS-lite v0.6 manual | Integrated section §7 of the lite manual"*
> — `team/roles/librarian/reality/ai-agents/index.md:99`

So: the most agent-usable part of Issues-FS is specified in a different repo, inside a document about a different protocol, in a section a reader would never find. That is the same routing failure that made agents under-weight the graph philosophy for months. **Fix it here.**

The full extracted specification — layout, file format, required and recommended front-matter, the four operations, the check-in cycle, and the read-but-never-write rule — is in `02__issues-fs-lite.md`. It is ~1,100 words and it is ready to publish.

⚠️ **And there is a second lite surface that nobody has written up at all:** the **`.issues` flat-file DSL** in the core package — 11 source files, ~55 tests, 3 live example files, wired into `Graph__Repository.issues_files_*`. **Zero prose documentation anywhere** — not in any README, brief or architecture doc. It is the newest and most distinctive feature in the codebase and it is invisible. See `04__what-ships.md` §5.

---

## 4. Real numbers the site can stand on

| | |
|---|---|
| **Live graph, SGraph Send** | **71 nodes · 141 link entries** · 84 files · max depth 8 path segments · all 13 schema fields present on all 71 nodes |
| Node types configured | **12** — `git-repo, bug, task, feature, person, project, phase, research, spike, security-review, threat-model, question` |
| Link types configured | **10** verb/inverse pairs with source/target constraints |
| Ecosystem-wide | **147 nodes** across 4 live graphs (Send 71 · Service__UI 49 · Issues-FS 24 · CLI 3) |
| Tests | **604** functions / 45 files (core) · **94** / 7 (CLI) · 8,213 test LOC |
| Core source | 98 `.py`, **5,401 LOC** — 1.5 test LOC per source LOC |
| CLI | **14 commands**, 3 output formats, **`--for-agent` on every one** |
| Storage backends | 4 real: `memory`, `local_disk`, `sqlite`, `zip` |
| Corpus | 59 documents in `Issues-FS__Docs`; ecosystem spans 2026-02-04 → 2026-02-22 |

---

## 5. Three things the site must get right

### 5.1 `--for-agent` is the story, not a footnote
Every one of the 14 CLI commands takes `--for-agent`, which forces JSON output. Combined with lite mode and the flat-file DSL, Issues-FS has **three distinct agent-operable surfaces**. No other project in the estate has that, and no current document says it out loud.

### 5.2 The claims that need correcting before republication
Four load-bearing claims appear in multiple READMEs and are false:

| Claim | Where | Reality |
|---|---|---|
| **S3 storage backend** | 4 places incl. two READMEs and `CLAUDE.md` | `Enum__Graph__Storage__Backend` has MEMORY / LOCAL_DISK / SQLITE / ZIP. memory-fs 0.41.0 ships no S3 provider |
| **MGraph-DB integration** | `Issues-FS/README.md`, `CLAUDE.md`, architecture overview | **`mgraph-db` is in zero `pyproject.toml` files and `import mgraph_db` in zero source files.** `issues_fs/mgraph/` is a hand-rolled ~220-LOC in-memory graph borrowing MGraph-DB's naming convention only |
| **`issues-fs-lexicon`** — *"required by every Issues-FS repository"* | Lexicon architecture v1 and v2, ~7,000 words | No repo, no PyPI package, in no `pyproject.toml`. **The most-theorised, least-built idea in the corpus** |
| Version / test counts | `Issues-FS/README.md` says v0.4.5, 475+ tests | Repo v0.7.1, PyPI 0.7.0, **604 tests** |

**Do not carry these onto the site.** Publish the corrected versions and — following the house convention — say plainly that the READMEs are behind.

### 5.3 The licence needs a decision before launch
All nine repos ship byte-identical **Apache 2.0**. But:
- **No copyright holder is named anywhere.** Every `LICENSE` ends with the unfilled `Copyright [yyyy] [name of copyright owner]`. No `NOTICE` file.
- `Issues-FS__Dev/README.md` claims *"Documentation and knowledge content are published under CC BY 4.0."* That sentence is the **only** occurrence of "CC BY" in the entire corpus. `Issues-FS__Docs` ships Apache 2.0 and says nothing about it. **No document carries a per-document licence line.**
- ~29,000 words (18% of the corpus) are imported briefings about MGraph-DB and OSBot-Utils with no source attribution.

Given the 21 August CC BY 4.0 decision for the `*.sgit.ai` estate, this needs resolving deliberately. Detail in `06__boundaries-and-house-style.md` §4.

---

## 6. Build order

| Step | Section | Why here | Status |
|---|---|---|---|
| **1** | **`/lite/`** — Issues-FS-lite, complete | The commissioning priority, homeless today, ~1,100 words ready to publish | ✍️ extract |
| **2** | **`/shipped/`** — the package table | The navigation job. Nothing like it exists; two empty wheels need saying out loud | ✍️ fresh |
| **3** | `/start/` — install, init, first graph in five minutes | `pip install issues-fs-cli` → `issues-fs init` → `create` → `link`. Real and verified | ✅ |
| **4** | `/concepts/` — the five foundational documents | Thinking in graphs, lexicon, compatibility, LLM-as-execution-engine, use-case pattern | ✅ near-as-is |
| **5** | `/model/` — nodes, edges, labels, the ID scheme | From code, not prose. `Safe_Str__Graph_Types.py` is the best teaching artefact in the repo | ✏️ |
| **6** | `/cli/` — 14 commands with real flags | Verified against source | ✅ |
| **7** | `/dsl/` — the `.issues` flat-file DSL | Built, tested, live examples, **zero documentation** | ✍️ fresh |
| **8** | `/roles/` — the 11-role agentic team | Self-referential: the tracker tracks its own development | ✅ |
| **9** | `/examples/` — the live SGraph Send graph | 71 nodes / 141 edges, downloadable | ✅ |
| **10** | `/network/` — boundaries with graphs.sgit.ai especially | See `06` §1 | ✏️ |

---

## 7. What is in this pack

| File | Contents |
|---|---|
| `00__BRIEF.md` | This document |
| `01__concepts-index.md` | The 14 concept documents with paths, word counts, newcomer-readiness |
| `02__issues-fs-lite.md` | **The complete lite specification, extracted and ready to publish** |
| `03__the-data-model.md` | Nodes, edges, labels, ID scheme, storage layout — from code |
| `04__what-ships.md` | The navigation deliverable: packages, CLI, service, UI, the DSL, honest maturity |
| `05__site-architecture.md` | Page-by-page IA with sources |
| `06__boundaries-and-house-style.md` | Sibling boundaries, the correction list, licensing, conventions |
| `07__gaps-and-open-questions.md` | Documented-not-built, built-not-documented, stale claims, open questions |
| `08__source-manifest.csv` | Machine-readable, every path verified |

---

This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).