ostler 0.1.0__tar.gz

ostler-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

ostler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Côté
+
+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.

ostler-0.1.0/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.4
+Name: ostler
+Version: 0.1.0
+Summary: Define, validate, search and mutate a repository's markdown knowledge graph (OKF profile: epics, stories, seeds, knowledge, features).
+Project-URL: Homepage, https://github.com/GabrielCpp/stablemate
+Project-URL: Repository, https://github.com/GabrielCpp/stablemate
+Project-URL: Issues, https://github.com/GabrielCpp/stablemate/issues
+Author: Gabriel Côté
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,docs,epics,knowledge,stories,validation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ostler
+
+> Tend your documentation graph.
+
+`ostler` is the single system-of-record for a repository's `docs/` knowledge graph. It **defines,
+validates, searches and mutates** your planning docs — epics, stories, seeds, knowledge records and
+features — as plain markdown **Concepts** (a strict profile of the
+[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)).
+
+Everything is markdown. An epic's seeds and its story dependency-DAG live inside its `epic.md`; there
+is **no** `seed.json`, `dependencies.json`, `inventory.json` or `epics-todo.json`. Ostler owns id
+allocation and is the one tool that reads and writes the graph — so structure stays consistent while
+humans (or agents) author the prose.
+
+It is a standalone, repo-agnostic CLI that operates relative to the **current working directory**:
+roots default to `<cwd>/docs/{epics,knowledge,features,specs}` and the organization name to the repo
+folder name. Point it at any repo with `-C/--chdir`.
+
+## Install
+
+```bash
+pipx install ostler          # recommended: isolated CLI on your PATH
+# or
+pip install ostler
+```
+
+For development against a local checkout:
+
+```bash
+pipx install --editable /path/to/stablemate/ostler --force
+```
+
+The package installs one console entry point, `ostler`.
+
+## Quickstart
+
+Ostler creates the *structure and ids*; you author the *content* into the skeletons it scaffolds.
+
+```bash
+# 1. See if the graph is healthy
+ostler doctor
+
+# 2. Scaffold an epic (allocates an id, writes docs/epics/checkout-flow/epic.md)
+ostler create epic checkout-flow --title "Checkout Flow at Parity"
+
+# 3. Record a seed (a unit of intended work) in that epic's ## Seeds
+ostler seed add checkout-flow address-step --status researched \
+  --surface checkout/address --summary "Collect & validate the shipping address"
+
+# 4. Cut a story that covers the seed (adds it to the epic's ## Stories, scaffolds story.md)
+ostler create story checkout-flow 01-address-step \
+  --title "Address step" --covers address-step
+
+# 5. Ask what to work on next, then list the epic's stories as JSON
+ostler next-story checkout-flow
+ostler list --type story --epic checkout-flow --json
+```
+
+Then open the scaffolded `epic.md` / `story.md` and write the narrative, acceptance criteria, and
+prose — ostler keeps the seeds, edges, ids and queue coherent around it.
+
+## The hierarchy
+
+A repository's knowledge lives under `docs/` as OKF **bundles** (directories of markdown Concepts).
+A **Concept** is one `.md` file with a YAML **frontmatter** block (whose only hard requirement is a
+non-empty `type`) and a markdown **body** using conventional headings.
+
+**Identity is the path.** A Concept's id is its bundle-relative path without `.md`
+(`docs/knowledge/profile/preference-summary.md` → `profile/preference-summary`). The reserved
+filenames `index.md` (an ordered listing of a bundle) and `log.md` (history) are not Concepts.
+
+### Entity types
+
+| `type` | Location (repo-relative) | Identity | Required frontmatter |
+|---|---|---|---|
+| `epic` | `docs/epics/<epic>/epic.md` | `<epic>` (dir name) | `type`, `id`, `title` |
+| `story` | `docs/epics/<epic>/stories/<slug>/story.md` | `<slug>` | `type`, `slug`, `status` |
+| `knowledge` | `docs/knowledge/<area>/<name>.md` | path (`surface` alias) | `type`, `surface` |
+| `feature` | `docs/features/<area>/<slug>.md` *(or flat `docs/features/<slug>.md`)* | `<area>/<slug>` | `type`, `slug`, `title` |
+| `spec.plan` / `spec.review` / `spec.qa` | `docs/specs/<slug>/*.md` | path | `type` |
+
+`spec.*` Concepts are process artifacts: typed and conformance-checked, but ostler does not own their
+internal schema. **Not Concepts** (managed markdown, left in place): `docs/backlog.md` (an intake list)
+and `docs/epics/index.md` (the epics queue).
+
+### `epic.md` — single source of truth for an epic
+
+An epic's `epic.md` carries the narrative **and** its seeds and story dependency-DAG. Ostler parses two
+canonical sections back out of the markdown by exact heading:
+
+```markdown
+---
+type: epic
+id: pred-15
+title: Account Credits "Aperçu" Billing Body at Legacy Parity
+status: in-progress        # optional: planned | in-progress | done
+---
+
+Free narrative prose (any headings: ## Goal, ## Method, ## Acceptance, …).
+
+## Seeds
+
+### apercu-landing-body
+- status: researched       # backlog | researched | covered | resolved | dropped | deferred
+- surface: account-billing/apercu-billing-body
+- legacySurface: /{_locale}/employe/profile/edit (BuyCreditsAction)
+- backing: GET /billing/customer → CustomerDetails
+
+The first paragraph after the metadata bullets is the seed summary; further prose is free markdown.
+
+## Stories
+
+### 01-apercu-billing-body
+- title: Account Credits "Aperçu" Billing Body at Legacy Parity
+- id: pred-16
+- covers: apercu-landing-body, apercu-subscription-change-plan-link
+- depends on: (none)
+- phase: 1
+- effort: 8-10 hours
+```
+
+- `## Seeds` → `### <seed-id>` per seed (omit the whole section for a seedless epic).
+- `## Stories` → `### <slug>` per story, carrying the **edges**: `covers:` (seed ids) and
+  `depends on:` (sibling slugs). The detailed spec lives in the story's own `story.md`.
+
+See [`SPEC.md`](SPEC.md) for the authoritative, formal definition of every field, status enum, and
+conformance rule.
+
+## Command interface
+
+All read commands accept `--json`. Mutating commands allocate ids as needed and write canonical
+markdown in place.
+
+**Global**
+
+```bash
+ostler --version
+ostler -C, --chdir DIR <command> …            # operate as if run from DIR
+```
+
+**Inspect**
+
+```bash
+ostler doctor [--epic SLUG] [--json] [--no-schema]   # conformance + referential integrity; non-zero on a break
+ostler trace  <id|slug|gap|surface|path>             # walk the graph from any node
+```
+
+**Retrieve**
+
+```bash
+ostler list  --type epic|story|knowledge|feature|spec|seed|gap [--epic E] [--status S] [--json]
+ostler search <query> [--type T] [--owner O] [--tag G] [--json]
+ostler query  gaps-in-story|stories-covering-seed|surfaces-referenced-by-story <arg> [--json]
+ostler next-epic [--json]                            # next queued epic with unfinished work
+ostler next-story <epic> [--json]                    # next runnable story (deps satisfied, not done)
+```
+
+**Mutate** (allocates ids, writes markdown)
+
+```bash
+ostler create epic    <name>  --title T [--prefix P] [--json]
+ostler create story   <epic> <slug> --title T [--covers a,b] [--depends a,b] [--prefix P] [--json]
+ostler create feature <slug>  --title T [--area A] [--route R] [--prefix P] [--json]
+ostler delete epic|story|feature <name>
+
+ostler seed add    <epic> <id> [--status S] [--summary …] [--surface …] \
+                               [--legacy-surface …] [--backing …] [--prerequisites …] [--source-bullet …]
+ostler seed remove <epic> <id>
+ostler set-status  <story> <status>
+
+ostler backlog add <id> <text> [--section S] | ostler backlog prune <id> | ostler backlog list [--json]
+ostler todo add <epic> [--front] | ostler todo prune <epic> | ostler todo reorder <e…> | ostler todo list [--json]
+```
+
+`create … --json` returns `{"ok": true, "id": "<allocated-id>", "message": "…"}`.
+
+**Repair / approve**
+
+```bash
+ostler edit set-owner <gap> <story> [--write]   # dry-run by default; --write applies
+ostler edit relink    <old-path> <new-path> [--write]
+ostler edit rename    <old-slug> <new-slug> [--write]
+ostler freeze   <ident> [--by WHO] [--note …]   # pin an approved story/seed as immutable ground truth
+ostler unfreeze <ident>
+```
+
+## The coverage model
+
+```
+knowledge gaps[].owner  ->  story (epic.md ## Stories)  ->  covers: seed (epic.md ## Seeds)
+```
+
+`ostler doctor` checks OKF conformance (every Concept has a non-empty `type`) plus the typed
+referential-integrity contract:
+
+- **cross-epic references** — an id/slug used inside epic E that only resolves in another epic;
+- **orphan seeds** — an active seed no story covers;
+- **dangling references** — a `[gap:…]` tag, knowledge path, or sibling slug that resolves to nothing;
+- **stale owners** — a non-resolved gap whose `owner` is empty or points at a missing story;
+- **frozen drift** — an approved (frozen) story/seed that changed or vanished.
+
+It exits non-zero when any error-level finding is present, so it drops straight into CI or a pre-commit
+hook. Warning-level findings (e.g. `story-covers-no-seed`, `ungrounded-surface`) are reported but do
+not fail the check.
+
+## Id allocation
+
+Ostler owns `.agents/ids.json` (`{prefix, counter, frozen}`). `create epic|story|feature` allocates the
+next `<prefix>-<n>` id atomically, scaffolds the canonical markdown, and (for stories) inserts the
+`### <slug>` block into the epic's `## Stories`. There is no external id allocator.
+
+## Profiles
+
+`ostler` infers a profile from the tree: **`full`** when `docs/epics` exists (the epic/story/seed/
+knowledge coverage graph), **`exploration`** otherwise (knowledge/docs only, no coverage graph).
+Override any default in an optional `organization:` block in `ostler.yml` / `agents.yml` at the repo
+root.
+
+## Versioning
+
+The format is the OKF profile **v1.0**, versioned `<major>.<minor>`. Minor bumps add backward-compatible
+fields; major bumps may change required frontmatter or the `epic.md` grammar. A repo may record
+`okf_version` and `ostler_profile` in `docs/epics/index.md`.
+
+## License
+
+See [`LICENSE`](LICENSE).