shelf-spec 0.1.0__tar.gz

shelf_spec-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor junk
+.DS_Store
+Thumbs.db
+*.swp
+* 2.*

shelf_spec-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0 (M0)
+
+- Pinned the MCP SDK by major (`mcp>=1.2.0,<2`): mcp 2.0.0 removed
+  `mcp.server.fastmcp`, so fresh installs failed to import the server.
+- **Project renamed `openshelf` → `shelf-spec`** (2026-07-26, ADR 0007;
+  closes the naming gate #3): package, console script, module
+  `shelf_spec`, env `SHELF_SPEC_ROOT` (was `OPENSHELF_ROOT`), schema `$id`,
+  repo URLs. Nothing had been published under the old name.
+- shelf-spec v0: `spec/SPEC.md` + `spec/shelf.schema.json` + examples.
+- Engine: manifest loader (schema validation, config-error gate),
+  spec validator with severities, idempotent scaffolder, info summary.
+- Thin MCP server (`shelf_init` / `shelf_validate` / `shelf_info`) and
+  CLI (`shelf-spec init|validate|info|serve`) over the same engine.
+- `shelf-spec validate --ci` with exit codes 0/1/2 for shelf-repo CI.
+- MCP tools take flat keyword arguments (`{"shelf_path": ...}` in
+  `tools/call`) instead of a single nested `params` model.
+- `docs/adoption/`: ready-to-apply `shelf.yml` candidates for the three
+  owner shelves (validated green via `--manifest`; committing them into
+  the shelf repos is an owner action).
+- Validator: a non-UTF-8 or unreadable `.meta.json` / `ledger.tsv` /
+  `.docshelf.json` now degrades to a normal finding instead of aborting
+  the CLI with a traceback (#6).
+- Validator: `extra_dirs` entries now suppress `category-undeclared` /
+  `orphaned-split-dir` for the declared sidecar directories, and a declared
+  directory missing on disk raises the `extra-dir-missing` info finding (#7).
+- Validator: new `episode-sections-missing` error enforces the required
+  H2 sections per episode kind (SPEC 5.3) (#8).

shelf_spec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filipp Ignatenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shelf_spec-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: shelf-spec
+Version: 0.1.0
+Summary: shelf-spec: portable, vendor-neutral agent memory as a git repo of Markdown — spec, validator, thin MCP server and CLI.
+Project-URL: Homepage, https://github.com/ignatenkofi/shelf-spec
+Project-URL: Repository, https://github.com/ignatenkofi/shelf-spec
+Author-email: Filipp Ignatenko <ignatenkofi@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent-memory,git,llm,markdown,mcp,model-context-protocol,spec
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shelf-spec
+
+**shelf-spec** — a portable, vendor-neutral memory format for AI agents —
+plus a thin validator/scaffolder around it.
+
+A *shelf* is a git repository of human-readable Markdown: categories, an
+`INDEX.md` catalog, per-category metadata, an optional journal
+(`ledger.tsv`) and policy (`POLICY.md`). Any MCP client attaches the same
+shelf; migration between vendors is `git clone`. The product is the
+**format** ([spec/SPEC.md](spec/SPEC.md)); the reference implementation is
+[docshelf-mcp](https://github.com/ignatenkofi/docshelf-mcp).
+
+Status: **v0 (draft, descriptive)** — the spec fixes what already works on
+live shelves. Final name: `shelf-spec` (decided 2026-07-26, ADR 0007; before
+the production repo).
+
+## What is in this repo
+
+- `spec/SPEC.md` — shelf-spec v0 (RFC 2119).
+- `spec/shelf.schema.json` — JSON Schema (draft 2020-12) for `shelf.yml`.
+- `spec/examples/` — example manifests (memory, document, reserved multi).
+- `src/shelf_spec/` — engine (manifest loader, validator, scaffolder, info)
+  with two thin transports: an MCP server and a CLI.
+- `docs/advisory-ci.md` — drop-in advisory CI stage for shelf repos.
+
+## Install
+
+```bash
+pip install -e '.[dev]'
+```
+
+## CLI
+
+```bash
+shelf-spec init PATH --name "My shelf" --profile memory --categories topics,research,sessions
+shelf-spec validate [PATH]              # human-readable report
+shelf-spec validate --ci [PATH]         # machine JSON on stdout, exit 0/1/2
+shelf-spec validate --json [PATH]       # JSON report
+shelf-spec validate --manifest CANDIDATE.yml PATH   # validate a tree against
+                                       # an external manifest without touching it
+shelf-spec info [PATH]                  # manifest + index summary for a client
+shelf-spec serve                        # MCP server on stdio
+```
+
+Exit codes: `0` — shelf conforms (warnings allowed; `--strict` promotes
+warnings to failure), `1` — spec violations (error findings), `2` —
+config-error (manifest missing / unparseable / schema-invalid; checked
+before any rule).
+
+The default shelf root is `$SHELF_SPEC_ROOT`, falling back to the current
+directory.
+
+## MCP server
+
+Three tools, same engine as the CLI:
+
+| tool | type | what it does |
+|---|---|---|
+| `shelf_init` | write (local) | scaffold a shelf: `shelf.yml`, docs root and categories, `POLICY.md` stub, `.gitignore`; idempotent |
+| `shelf_validate` | read | lint a shelf against the spec; report with findings and severities |
+| `shelf_info` | read | manifest + index summary for a connecting client |
+
+Tools take flat keyword arguments — a hand-written `tools/call` looks like
+`{"name": "shelf_validate", "arguments": {"shelf_path": "/path/to/shelf"}}`,
+no wrapper object.
+
+Client configuration (stdio):
+
+```json
+{
+  "mcpServers": {
+    "shelf-spec": {
+      "command": "shelf-spec",
+      "args": ["serve"],
+      "env": { "SHELF_SPEC_ROOT": "/path/to/your/shelf" }
+    }
+  }
+}
+```
+
+Validation and info never scaffold a shelf silently: pointing them at a
+directory without a manifest is a config-error, not an invitation to
+create one.
+
+## Compatibility promise
+
+An existing docshelf/memshelf shelf becomes spec-conformant by adding
+**one file** — `shelf.yml` with `mode: single`. Nothing is migrated
+(ADR-0005). `.docshelf.json` remains a legal implementation detail;
+`shelf.yml` is the contract. Ready-to-apply manifests for the shelves
+named in the roadmap live in [`docs/adoption/`](docs/adoption/README.md).
+
+## License
+
+MIT.

shelf_spec-0.1.0/README.md

@@ -0,0 +1,95 @@
+# shelf-spec
+
+**shelf-spec** — a portable, vendor-neutral memory format for AI agents —
+plus a thin validator/scaffolder around it.
+
+A *shelf* is a git repository of human-readable Markdown: categories, an
+`INDEX.md` catalog, per-category metadata, an optional journal
+(`ledger.tsv`) and policy (`POLICY.md`). Any MCP client attaches the same
+shelf; migration between vendors is `git clone`. The product is the
+**format** ([spec/SPEC.md](spec/SPEC.md)); the reference implementation is
+[docshelf-mcp](https://github.com/ignatenkofi/docshelf-mcp).
+
+Status: **v0 (draft, descriptive)** — the spec fixes what already works on
+live shelves. Final name: `shelf-spec` (decided 2026-07-26, ADR 0007; before
+the production repo).
+
+## What is in this repo
+
+- `spec/SPEC.md` — shelf-spec v0 (RFC 2119).
+- `spec/shelf.schema.json` — JSON Schema (draft 2020-12) for `shelf.yml`.
+- `spec/examples/` — example manifests (memory, document, reserved multi).
+- `src/shelf_spec/` — engine (manifest loader, validator, scaffolder, info)
+  with two thin transports: an MCP server and a CLI.
+- `docs/advisory-ci.md` — drop-in advisory CI stage for shelf repos.
+
+## Install
+
+```bash
+pip install -e '.[dev]'
+```
+
+## CLI
+
+```bash
+shelf-spec init PATH --name "My shelf" --profile memory --categories topics,research,sessions
+shelf-spec validate [PATH]              # human-readable report
+shelf-spec validate --ci [PATH]         # machine JSON on stdout, exit 0/1/2
+shelf-spec validate --json [PATH]       # JSON report
+shelf-spec validate --manifest CANDIDATE.yml PATH   # validate a tree against
+                                       # an external manifest without touching it
+shelf-spec info [PATH]                  # manifest + index summary for a client
+shelf-spec serve                        # MCP server on stdio
+```
+
+Exit codes: `0` — shelf conforms (warnings allowed; `--strict` promotes
+warnings to failure), `1` — spec violations (error findings), `2` —
+config-error (manifest missing / unparseable / schema-invalid; checked
+before any rule).
+
+The default shelf root is `$SHELF_SPEC_ROOT`, falling back to the current
+directory.
+
+## MCP server
+
+Three tools, same engine as the CLI:
+
+| tool | type | what it does |
+|---|---|---|
+| `shelf_init` | write (local) | scaffold a shelf: `shelf.yml`, docs root and categories, `POLICY.md` stub, `.gitignore`; idempotent |
+| `shelf_validate` | read | lint a shelf against the spec; report with findings and severities |
+| `shelf_info` | read | manifest + index summary for a connecting client |
+
+Tools take flat keyword arguments — a hand-written `tools/call` looks like
+`{"name": "shelf_validate", "arguments": {"shelf_path": "/path/to/shelf"}}`,
+no wrapper object.
+
+Client configuration (stdio):
+
+```json
+{
+  "mcpServers": {
+    "shelf-spec": {
+      "command": "shelf-spec",
+      "args": ["serve"],
+      "env": { "SHELF_SPEC_ROOT": "/path/to/your/shelf" }
+    }
+  }
+}
+```
+
+Validation and info never scaffold a shelf silently: pointing them at a
+directory without a manifest is a config-error, not an invitation to
+create one.
+
+## Compatibility promise
+
+An existing docshelf/memshelf shelf becomes spec-conformant by adding
+**one file** — `shelf.yml` with `mode: single`. Nothing is migrated
+(ADR-0005). `.docshelf.json` remains a legal implementation detail;
+`shelf.yml` is the contract. Ready-to-apply manifests for the shelves
+named in the roadmap live in [`docs/adoption/`](docs/adoption/README.md).
+
+## License
+
+MIT.

shelf_spec-0.1.0/adr/README.md

@@ -0,0 +1,12 @@
+# ADR-индекс пакета 07 (shelf-spec, ранее openshelf)
+
+Все решения в статусе `proposed` до старта реализации (HANDOFF-паттерн полки).
+
+| ADR | Решение |
+|---|---|
+| [0001](0001-spec-first-not-another-memory-store.md) | Спек-первичность: формат — продукт, сервер — референс; не ещё один memory-store |
+| [0002](0002-git-native-concurrency-advisory-leases.md) | Git-native конкурентность + advisory-леазы; не lock-сервер, не CRDT |
+| [0003](0003-memory-is-data-not-instructions.md) | «Память — данные, не инструкции» как требование протокола (анти-poisoning) |
+| [0004](0004-zones-roles-dual-enforcement.md) | Зоны/роли в `agents.yml`, двухплоскостной enforcement (сервер + линт при мёрже) |
+| [0005](0005-extract-spec-from-existing-shelves.md) | Спек извлекается из docshelf/memshelf; они — reference, ничего не переписываем |
+| [0006](0006-byom-no-vendor-memory-sync.md) | BYOM: вендорскую память не синхронизируем — полка её заменяет |

shelf_spec-0.1.0/docs/adoption/README.md

@@ -0,0 +1,41 @@
+# Adoption kit — shelf.yml candidates for the owner's shelves
+
+Ready-to-apply `shelf.yml` manifests for the three existing shelves named
+in the M0 roadmap. Each one makes its shelf spec-conformant by adding a
+single file (`mode: single`, compatibility promise of ADR-0005) — nothing
+else migrates.
+
+| candidate | target shelf | profile | notes |
+|---|---|---|---|
+| `sqst-memshelf.shelf.yml` | sqst-memshelf | memory | ledger + policy declared |
+| `unevie-shelf.shelf.yml` | unevie-shelf | document | older `.docshelf.json` stays valid |
+| `homelab-shelf.shelf.yml` | homelab-shelf | document | pre-docshelf: nested docs root, external index, extra dirs |
+
+All three validate green (`exit 0`, zero error findings) against the live
+clones via the external-manifest mode, which needs no write access to the
+shelf:
+
+```bash
+shelf-spec validate --ci --manifest docs/adoption/<shelf>.shelf.yml /path/to/<shelf>
+```
+
+## Status: drafted, not yet applied
+
+Committing these files **into the shelf repositories is an owner action**
+— the shelf repos are outside this repository and were treated as
+read-only during M0. Until then this directory is the canonical home of
+the candidates (they must not live only in a session handoff). To apply:
+
+1. Copy the candidate to the shelf root as `shelf.yml`
+   (drop the `<shelf>.` prefix).
+2. Run `shelf-spec validate --ci .` in the shelf root — expect exit 0.
+3. Commit; optionally add the advisory CI stage from
+   [`../advisory-ci.md`](../advisory-ci.md) in the same change.
+
+Expected non-blocking findings on today's clones (exit code stays 0):
+sqst-memshelf — none; unevie-shelf — `remote-mismatch` warning,
+`no-policy` info; homelab-shelf — `remote-mismatch` and one `stale-index`
+warning, `no-policy` info.
+
+Once the candidate is merged as `shelf.yml`, delete it from this
+directory — the shelf's own copy becomes the source of truth.

shelf_spec-0.1.0/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shelf-spec"
+dynamic = ["version"]
+description = "shelf-spec: portable, vendor-neutral agent memory as a git repo of Markdown — spec, validator, thin MCP server and CLI."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Filipp Ignatenko", email = "ignatenkofi@gmail.com" }
+]
+keywords = ["mcp", "model-context-protocol", "agent-memory", "markdown", "git", "spec", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+
+dependencies = [
+    # mcp 2.0.0 removed mcp.server.fastmcp — pin the SDK by major.
+    "mcp>=1.2.0,<2",
+    "pydantic>=2.6",
+    "pyyaml>=6.0",
+    "jsonschema>=4.21",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5.0",
+]
+
+[project.scripts]
+shelf-spec = "shelf_spec.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/ignatenkofi/shelf-spec"
+Repository = "https://github.com/ignatenkofi/shelf-spec"
+
+[tool.hatch.version]
+path = "src/shelf_spec/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shelf_spec"]
+
+[tool.hatch.build.targets.wheel.force-include]
+# The canonical schema lives in spec/ (single source of truth); ship a copy
+# inside the wheel so the installed package can validate manifests offline.
+"spec/shelf.schema.json" = "shelf_spec/spec/shelf.schema.json"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/",
+    "tests/",
+    "spec/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "UP", # pyupgrade
+]
+ignore = ["E501"]  # line too long — handled by formatter
+
+[tool.ruff.lint.isort]
+known-first-party = ["shelf_spec"]