sgit newsroom v0.1.29 · snapshot 2026-09-24

Reading room · issues-fs.sgit.ai

On this page

Reading room / issues-fs.sgit.ai · raw text · live ↗

From issues-fs.sgit.ai, the page as fetched on 2026-09-24 · open the live page ↗Everything on this sheet is the source site's own text; the newsroom's chrome is outside it.

issues-fs.sgit.ai — 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 — so the tracker lives inside the repository it tracks, versions with it, branches with it, and can be read by cat, grep and find. Issues-FS has THREE agent-operable surfaces, which no other project in the estate has.

Site version: v0.1.2 (22 August 2026). Published by the sgit project, which builds and uses Issues-FS — participant disclosure at /about/participant.html. Site content CC BY 4.0; the upstream Issues-FS repositories are Apache 2.0.

What is built, in numbers

5,401 lines of source across 98 files in the core library, with 604 test functions across 45 files behind it (8,213 test LOC — 1.5 lines of test per line of source). A CLI of 1,080 lines with 14 commands and 94 tests. A type system of 12 node types and 10 link types where an edge type carries a declared inverse AND domain/range constraints, over five regex-validated primitives in strict mode. Four real storage backends. Four live graphs holding 147 nodes, the largest with 71 nodes, 141 link entries and depth 8. A corpus of 59 documents, five of which became the conceptual foundation of the whole *.sgit.ai estate. Eleven agentic roles, each its own repository with its own ROLE.md and its own .issues/.

Install it

Quickstart, every command verified against source: issues-fs init; issues-fs types init; issues-fs create task "..." --priority high --tags a,b; issues-fs link Task-1 blocks Bug-1; issues-fs list --for-agent The CLI walks UP from the working directory to find .issues/, like git, so it works from anywhere in the tree. WART: -p is --path on init and --priority on create/update; --depth is -D. Prefer long option names.

Properties agents may rely on

The three agent-operable surfaces

  1. Issues-FS-lite — https://issues-fs.sgit.ai/lite/index.html ↗ NO INSTALL AT ALL. Three folders — issues/open/, issues/blocked/, issues/done/ — markdown files with YAML front-matter named NNN-kebab-slug.md on a PER-AGENT counter, and FOUR mv operations: OPEN, BLOCK, UNBLOCK, CLOSE. Required front-matter is created (UTC ISO 8601) and priority; recommended are source, estimated_effort, blocked_on and parent. The body is your own action plan — the specification's own instruction is that if you do not know how to approach it yet, WRITE THAT DOWN. Commit issue changes in the same commit as the work that caused them. Status: specification only, complete and usable; no implementation is needed and none exists.

    • /lite/five-minutes.html — a worked example: three tasks, one blocked and unblocked, one closed, every command real. Nothing in the corpus had this.
    • /lite/vs-full.html — the comparison, and the honest statement that THERE IS NO LITE-TO-FULL CONVERTER and the identity schemes do not correspond.
    • /lite/team-view.html — the writer rule: you CAN read another agent's issues/ folder, you must NOT write into it. Tasks arrive by request. Each agent owns their own work plan. find . -path '*/issues/open/*.md' is a whole-team status view and it is free, out of the layout.

  2. The .issues flat-file DSL — https://issues-fs.sgit.ai/dsl/index.html ↗ A line-oriented text format parsed into graph nodes, inside the core package: 11 source files under issues_fs/issues/issues_file/, ~55 tests, three live example files, wired into Graph__Repository.issues_files_discover / load / get_cached_nodes / find_node_by_label / invalidate_cache. THERE IS NO WRITTEN GRAMMAR — the parser tests and the three live files are the only specification that exists, so read Parser__Issues_File__Line.py before writing one, load through the repository API rather than the parser directly, and pin the issues-fs version. No CLI command touches it. This page is the first prose documentation of it anywhere.

  3. --for-agent JSON — https://issues-fs.sgit.ai/cli/index.html ↗ EVERY ONE of the 14 CLI commands takes --for-agent, which forces JSON regardless of --output. That one rule is enough to drive the entire surface.

What is on PyPI, and what is queued

The docs describe an earlier version — check before repeating a claim

The upstream READMEs are behind the code, and every difference runs the same direction: there is MORE than they claim, not less. Four are load-bearing. Full list with what was measured: https://issues-fs.sgit.ai/shipped/corrections.html ↗

  1. There is NO S3 / cloud object-store backend — it was considered, not taken. The enum is MEMORY, LOCAL_DISK, SQLITE, ZIP. Claimed in four documents.
  2. There is NO MGraph-DB integration — the naming convention was borrowed, the library was not. The dependency appears in zero pyproject.toml files and the import in zero source files. What exists is a hand-rolled ~220-LOC in-memory graph borrowing the naming convention only.
  3. There is NO issues-fs-lexicon package — it is a design, not a dependency. No repo, no PyPI entry, in no pyproject.toml — despite ~7,000 words describing it as required by every Issues-FS repository.
  4. The test count is 604 (core, across 45 files) and 94 (CLI, across 7). READMEs say "475+" and "552+" — two different wrong numbers.

Also: pip install issues-fs-docs and pip install issues-fs-dev-utils do not resolve yet — both repositories are built but their dev branch has not reached main, and CI publishes only from main. There are 19 submodules (not 17) and 11 roles (not 10).

Using it

The data model

The ideas, and where they came from

The live graphs

The network, and what is not known

Site engineering