# 02 — Issues-FS-lite: the agent mode

**This is the priority page for the site.** It is also the one piece of Issues-FS with no home document today.

---

## 1. The situation

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

**Where the specification lives today:** §7 of
`team/humans/dinis_cruz/briefs/05/06/email-fs-lite-v0.6.md` — **in the `SGraph-AI__App__Send` repo**, inside an 8,229-word user manual about the *Email-FS-lite* protocol.

The Librarian's reality file records it precisely:

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

And the sibling comparison document explains *why* it was written there:

> *"**Issues-FS-lite integrated, not separate.** … Specified in one user manual that also covers Issues-FS-lite (task tracking) since the two are inseparable in the manual workflow."*
> — `team/humans/dinis_cruz/briefs/05/06/email-fs-comparison.md:14`

That reasoning is sound for a *workflow* manual. It is wrong for *discoverability*: an agent looking for how to use Issues-FS will never find a section about issues inside a document about email, in a repository for a different product.

**The fix is this page.** Publish it standalone, keep the Email-FS-lite manual as the integrated-workflow reference, and cross-link.

---

## 2. The specification, extracted

Source: `email-fs-lite-v0.6.md` §7 (lines 625–747), 6 May 2026, protocol version lite v0.6.
Reproduce faithfully; the wording below is close to verbatim and should be checked against source before publishing.

### 2.1 Why issues live beside messages

> *"When you receive an email, you usually do three things: (a) understand what it asks, (b) decide what tasks it generates for you, (c) reply or act. Issue tracking captures (b) — the agent's interpretation of the email turned into a plan."*
>
> *"When the issue updates land **in the same commit** as the email DELIVER and any response, the commit becomes a coherent record: 'this email arrived → here's what I planned to do about it → here's what I sent in reply.' **That trace is the unit of agent cognition.**"*

For a standalone page, generalise: issues live beside whatever generated them, and the commit is the record of what the agent understood.

### 2.2 Layout

```
mail/{your-agent-name}/issues/
├── open/                       ← active tasks
│   ├── 001-incorporate-v07-feedback.md
│   ├── 002-write-comparison-doc.md
│   └── 008-incorporate-v07-feedback.md
├── blocked/                    ← waiting on something external
│   └── 005-pkce-token-rotation-q.md
└── done/                       ← completed tasks
    ├── 003-route-prefix-decision.md
    └── 007-handoff-pkce-implementation.md
```

Lifecycle `open → done`, plus `blocked/` "because tasks have a richer flow than messages."

Filenames: `NNN-kebab-slug.md`. Sequence is **per-agent** — your own counter, independent of any other.

### 2.3 Task file format

```markdown
---
created: 2026-05-06T18:00:00Z
source: mail/architect.spec/inbox/003-feedback-on-spec.eml
priority: high
estimated_effort: medium
---

# Incorporate v0.7 feedback into the draft

## What needs doing

@Code's feedback on spec §4 had three concrete points:
- Replace implicit grant with PKCE (line 47)
- Add code_challenge_method: S256 requirement (line 51)
- Add 5-min auth-code TTL note (line 58)

## How I'll approach it

1. Open the v0.7 draft
2. Apply each edit
3. Update the changelog
4. Send the updated draft back to @Code for verification

## Acceptance criteria

- All three lines updated
- Changelog reflects the changes
- @Code confirms via reply
```

**Required front-matter**

| Field | Purpose |
|---|---|
| `created` | UTC ISO 8601 |
| `priority` | `low` / `normal` / `high` / `urgent` |

**Recommended front-matter**

| Field | Purpose |
|---|---|
| `source` | Path to the artefact that generated this task. Empty for self-generated |
| `estimated_effort` | `small` / `medium` / `large` |
| `blocked_on` | If in `blocked/`: what we are waiting for — a path, or free text |
| `parent` | If a sub-step, the path to the parent task |

> *"The body of the task file is your own action plan. **Be honest — if you don't know how to approach it yet, write that.** Future you (or a different runtime) will read this."*

That instruction is worth featuring. It is the whole design philosophy in one line.

### 2.4 The four operations

> *"That's the entire issues protocol. **Four `mv` operations.**"*

| Op | Action |
|---|---|
| **OPEN** | Write a file in `issues/open/` with the next sequence number. When incoming work generates a task, do this in the same commit as the delivery |
| **BLOCK** | `mv` from `open/` to `blocked/`, add a `blocked_on:` field naming what you are waiting for, and note the blocker in the body too |
| **UNBLOCK** | `mv` from `blocked/` back to `open/`. Append a body section noting the blocker resolved |
| **CLOSE** | `mv` from `open/` or `blocked/` to `done/`. Append a body section summarising the outcome |

### 2.5 The check-in cycle

```
DELIVER incoming message
  → if it generates tasks:        OPEN one or more issues
  → if it answers a blocker:      UNBLOCK the corresponding issue
  → if it acknowledges work:      CLOSE the corresponding issue

SEND outgoing message
  → if it asks a blocking question: BLOCK the relevant issue
  → if it hands off work:           CLOSE the corresponding issue
  → if it creates a task for us:    OPEN a follow-up

DONE incoming message
  → only if all related issues are closed too
```

> *"**Every email cycle leaves the inbox cleaner and the issues folder updated.** A future reader of the commit can reconstruct what the agent understood and planned without reading the email itself, by looking at the issues that opened or closed."*

### 2.6 The writer rule, and the free team view

> *"You CAN read another agent's `issues/` folder. You should NOT write into it."*

```bash
find mail -path '*/issues/open/*.md'      # every open task across the team
find mail -path '*/issues/blocked/*.md'   # everything blocked
```

> *"This is a powerful at-a-glance team-status view, and **it's free — it falls out of the layout**."*
>
> *"The protocol doesn't permit one agent to add tasks to another's queue directly — only by request via mail. **This is intentional: each agent owns their own work plan.**"*

**Publish that last rule prominently.** It is a genuine design position on multi-agent coordination, and it is the sort of claim the sibling sites are built on.

---

## 3. What the standalone page must add

The extracted §7 is complete as a protocol but assumes the email context. Four additions for a standalone `/lite/`:

1. **A context-free opening.** "You are an agent with a filesystem and no tools. Here is how to track work." Drop the `mail/{agent}/` prefix assumption and state the layout as `{your-workspace}/issues/`, noting that in an Email-FS-lite vault it sits under `mail/{your-agent-name}/`.
2. **The relationship to full Issues-FS** — see §4 below. A reader must be able to see the two side by side and pick.
3. **A worked five-minute example** — three tasks, one blocked, one closed, with the actual commands. Nothing in the corpus has this.
4. **The upgrade path.** What happens when a lite graph outgrows lite? Honest answer: **there is no converter today.** State it rather than implying one.

---

## 4. Lite vs full — the comparison table the site needs

Built from measured facts, not marketing.

| | **Issues-FS-lite** | **Issues-FS (full)** |
|---|---|---|
| **Install** | Nothing | `pip install issues-fs-cli` |
| **Runtime** | None. `cat`, `mv`, `find` | Python ≥3.12 |
| **Storage** | Markdown + YAML front-matter | JSON (`issue.json`) per node |
| **States** | `open` / `blocked` / `done` — folders | Per-type configurable `statuses[]` |
| **Identity** | `NNN-kebab-slug.md`, per-agent sequence | `Node_Id` 10-char GUID + `Bug-27`-style label |
| **Edges** | `source:` and `parent:` front-matter | Typed verb/inverse pairs, stored on both endpoints |
| **Type system** | None — convention only | 12 node types, 10 link types, domain/range constrained |
| **Query** | `find` and `grep` | `Node__Service.traverse_graph`, `find_incoming_links` |
| **Backends** | Filesystem | `memory` / `local_disk` / `sqlite` / `zip` |
| **Agent output** | Native — it is all text | `--for-agent` forces JSON on all 14 commands |
| **Multi-agent** | Writer rule; own-queue-only | Not addressed |
| **Tests** | n/a | 604 core + 94 CLI |
| **Status** | **Specification only.** No reference implementation, no validator, no live example | Shipping. `issues-fs` 0.7.0 on PyPI |

**The honest line for the page:** *"Lite is a usage profile, not a fork"* — the phrasing the comparison document already uses (`email-fs-comparison.md:253`).

---

## 5. ⚠️ The third surface nobody has documented

There is a **`.issues` flat-file DSL** inside the core package — a line-oriented text format parsed into nodes:

- **11 source files** — `issues_fs/issues/issues_file/`: `Parser__Issues_File`, `Parser__Issues_File__Line`, `Issues_File__Loader__Service`, `Issues_File__Check__Service`, `Issues_File__Normalise__Service`, `Issues_File__Schema__Service`, `Factory__Issues_File__Nodes`
- **~55 tests** across 7 test files
- **3 live example files** in `Issues-FS`'s own `.issues/`: `bugs-parser.issues`, `workstream-integration.issues`, `workstream-issues-file-parser.issues`
- Wired into the repository API: `Graph__Repository.issues_files_discover / load / get_cached_nodes / find_node_by_label / invalidate_cache`

**It has zero prose documentation anywhere** — not in any README, brief or architecture document. It is the newest and most distinctive feature in the codebase.

For a site whose remit includes "what already exists and has shipped", this is a significant find: **Issues-FS has three agent-operable surfaces — lite markdown, the `.issues` DSL, and `--for-agent` JSON — and only one of them is documented at all.** Consider a `/dsl/` page alongside `/lite/`; the parser tests and the three live files are the specification until someone writes one.

---

## 6. Sources

| What | Path |
|---|---|
| The lite specification | `SGraph-AI__App__Send` → `team/humans/dinis_cruz/briefs/05/06/email-fs-lite-v0.6.md` §7 (lines 625–747) |
| Full manual (context) | same file, 8,229 words, 12 sections + Appendix A |
| Why integrated, and "lite is a usage profile, not a fork" | `team/humans/dinis_cruz/briefs/05/06/email-fs-comparison.md` (2,927 w) |
| Status of record | `team/roles/librarian/reality/ai-agents/index.md:99` |
| Architect assessment | `team/roles/architect/reviews/05/07/v0.27.7__architect-review__briefs-06-may.md` §4 |
| Master index entry | `team/roles/librarian/reviews/05/07/v0.27.7__master-index__briefs-06-may.md:62` |
| The undocumented DSL | `ifs-modules/Issues-FS/issues_fs/issues/issues_file/` + `Issues-FS/.issues/*.issues` |

⚠️ **Licence note:** the lite specification lives in `SGraph-AI__App__Send`, which is under the CC BY 4.0 decision of 21 August 2026. The Issues-FS repos are Apache 2.0. Publishing lite on `issues-fs.sgit.ai` moves a document across that boundary — state the source licence per `06__boundaries-and-house-style.md` §4.

---

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