oifmd 0.1.0.dev0__tar.gz → 0.1.0.dev1__tar.gz

{oifmd-0.1.0.dev0 → oifmd-0.1.0.dev1}/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2026 The Open Issue Format contributors
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

oifmd-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: oifmd
+Version: 0.1.0.dev1
+Summary: Open Issue Format (OIF) validator and tools
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://oif.md/SPEC.md
+Project-URL: Changelog, https://github.com/oifmd/oifmd/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://oif.md
+Project-URL: Source, https://github.com/oifmd/oifmd
+Keywords: oif,issues,issue-tracker,markdown,frontmatter,okf,git,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# Open Issue Format (OIF)
+
+![Open Issue Format](https://oif.md/oif-header-1500x500.png)
+
+**Issues and review comments as files, in any git repository, about
+anything in it.**
+
+An issue is a Markdown file whose directory is its state. A comment is a
+create-only file recording who said what, when, about which issue or
+which path at which commit. Concurrent comments never conflict. Nothing
+installed, and nothing written into the files being discussed.
+
+- **Spec:** [SPEC.md](https://github.com/oifmd/oifmd/blob/main/SPEC.md)
+- **Site:** https://oif.md
+- **Package:** `oifmd` (validator)
+
+## Sixty-second tour
+
+```
+board.md
+issues/
+├── backlog/
+│   ├── column.md
+│   └── add-jira-importer-nkhnsk.md
+├── doing/
+│   ├── column.md
+│   └── fix-login-redirect-loop-7k2x9m.md
+└── done/
+    ├── column.md
+    └── write-spec-outline-h87456.md
+```
+
+The directory is the status. The filename is the identity. Moving an
+issue is `git mv issues/doing/fix-login-redirect-loop-7k2x9m.md issues/done/`.
+
+`issues/doing/fix-login-redirect-loop-7k2x9m.md`:
+
+```markdown
+---
+type: issue
+resource: oif:app/7k2x9m
+title: Login form rejects passwords containing "!"
+kind: bug
+priority: high
+assignees: [coder/1.4]
+requested_by: human:sam
+tags: [auth]
+about:
+  - path: src/LoginForm.svelte
+    commit: 3f9c2e1
+created: 2026-09-13T03:10:00Z
+---
+
+Submitting a correct password with `!` clears the form and shows
+"invalid credentials". Expected: login succeeds.
+
+## Acceptance Criteria
+
+- [x] Reproduce with a failing test
+- [ ] Fix without changing the hashing path
+
+```
+
+Comments are separate files, one per comment, keyed by the issue's id:
+
+`comments/7k2x9m/k3n2wp.md`
+
+```markdown
+---
+type: comment
+at: 2026-09-13T04:12:00Z
+by: human:sam
+kind: verdict
+result: changes_requested
+---
+
+Keep the strip for whitespace only.
+```
+
+Read an issue and its whole history with one command:
+
+```sh
+cat issues/*/*-7k2x9m.md comments/7k2x9m/*.md
+```
+
+Find what the board says about a file before you touch it:
+
+```sh
+grep -rl -- 'src/LoginForm.svelte' .     # or: oifmd about src/LoginForm.svelte
+```
+
+Not everything has a lifecycle. A standalone comment records a judgement
+with no work attached, at `comments/<id>.md`:
+
+```markdown
+---
+type: comment
+at: 2026-09-15T04:10:00Z
+by: human:sam
+kind: confirms
+about:
+  - path: docs/orders.md
+    commit: 3f9c2e1
+---
+
+Checked against the billing code at this commit. Holds.
+```
+
+## Install
+
+The format needs no tool. The validator is there when you want the
+conformance list in section 8 of the spec checked for you.
+
+```sh
+pip install oifmd
+
+oifmd validate <board>      # check a board against the spec
+oifmd about <path>          # what the board says about a file
+oifmd new <board> todo "…"  # create an issue with a fresh id
+```
+
+## Why
+
+Several tools got here first and independently reached the same shape:
+Markdown plus frontmatter, one file per issue, living in the repo.
+[Backlog.md](https://github.com/MrLesk/Backlog.md),
+[beads](https://github.com/steveyegge/beads),
+[git-issues](https://steviee.github.io/git-issues/) and
+[beaver-backlog](https://github.com/builtbystef/beaver-backlog) each
+worked it out on their own, and OIF is built on what they demonstrated.
+
+What is missing is the format itself, written down apart from any one
+tool: a specification you can implement against, a validator that says
+whether a board conforms, and a version number so it can change without
+breaking readers. That is what this is. Issues outlive whichever tool
+wrote them, and any agent can read a board cold.
+
+Design rules that fall out of being agent-first and git-native:
+
+- **State is the directory.** A move is one atomic rename, not a
+  read-modify-write that two agents can trample.
+- **Identity is a random six-character id in the filename.** Two
+  branches can create issues at once and merge with no counter, no
+  scan, no renumbering. Sequential keys like `APP-2753` survive as
+  aliases.
+- **Records point at things; things never point back.** Everything is
+  written under the board root, so a board can describe a vendored
+  dependency, a submodule, a generated tree or a repo you only cloned to
+  review. The target's own tooling sees no diff.
+- **One comment is one file**, keyed by the issue's id. Two agents
+  commenting at once write two different paths, so nothing conflicts and
+  nothing is lost. Appending to a shared file does not survive concurrent
+  writers; see SPEC.md section 7.1.
+- **Unknown keys pass through.** A conforming consumer never rejects
+  them and keeps them when it rewrites a file.
+- **Every column has a `column.md`.** It keeps empty columns in git and
+  tells an arriving agent what belongs there and how to leave.
+- **The board declares its own vocabulary.** `board.md` lists the columns
+  and, optionally, the `kinds` an issue may have and which kinds may
+  contain which. Epic, story and task are one team's words, not the
+  format's. Ready `board.md` files for Kanban, Scrum and Shape Up are in
+  [`profiles/`](https://github.com/oifmd/oifmd/blob/main/profiles).
+
+An OIF board is a conforming [Open Knowledge Format](https://okf.md)
+bundle: same substrate, same actor convention, `type: issue` on every
+file. The one deliberate divergence, identity by id rather than by path,
+is spelled out in SPEC.md section 9. A tracker is a service you log into; OIF is a
+directory you already have.
+
+## This repository
+
+The roadmap for OIF itself lives in [`board/`](https://github.com/oifmd/oifmd/blob/main/board), in OIF.
+GitHub Issues stays open for conversation; accepted work lands in
+`board/issues/` with the GitHub number kept in `external_ids`.
+
+
+## License
+
+Apache-2.0.
+
+Open Issue Format is an independent specification, not affiliated with
+or endorsed by Google. Open Knowledge Format, OKF and Google are marks
+of their respective owners. See SPEC.md section 10.

oifmd-0.1.0.dev1/README.md

@@ -0,0 +1,183 @@
+# Open Issue Format (OIF)
+
+![Open Issue Format](https://oif.md/oif-header-1500x500.png)
+
+**Issues and review comments as files, in any git repository, about
+anything in it.**
+
+An issue is a Markdown file whose directory is its state. A comment is a
+create-only file recording who said what, when, about which issue or
+which path at which commit. Concurrent comments never conflict. Nothing
+installed, and nothing written into the files being discussed.
+
+- **Spec:** [SPEC.md](https://github.com/oifmd/oifmd/blob/main/SPEC.md)
+- **Site:** https://oif.md
+- **Package:** `oifmd` (validator)
+
+## Sixty-second tour
+
+```
+board.md
+issues/
+├── backlog/
+│   ├── column.md
+│   └── add-jira-importer-nkhnsk.md
+├── doing/
+│   ├── column.md
+│   └── fix-login-redirect-loop-7k2x9m.md
+└── done/
+    ├── column.md
+    └── write-spec-outline-h87456.md
+```
+
+The directory is the status. The filename is the identity. Moving an
+issue is `git mv issues/doing/fix-login-redirect-loop-7k2x9m.md issues/done/`.
+
+`issues/doing/fix-login-redirect-loop-7k2x9m.md`:
+
+```markdown
+---
+type: issue
+resource: oif:app/7k2x9m
+title: Login form rejects passwords containing "!"
+kind: bug
+priority: high
+assignees: [coder/1.4]
+requested_by: human:sam
+tags: [auth]
+about:
+  - path: src/LoginForm.svelte
+    commit: 3f9c2e1
+created: 2026-09-13T03:10:00Z
+---
+
+Submitting a correct password with `!` clears the form and shows
+"invalid credentials". Expected: login succeeds.
+
+## Acceptance Criteria
+
+- [x] Reproduce with a failing test
+- [ ] Fix without changing the hashing path
+
+```
+
+Comments are separate files, one per comment, keyed by the issue's id:
+
+`comments/7k2x9m/k3n2wp.md`
+
+```markdown
+---
+type: comment
+at: 2026-09-13T04:12:00Z
+by: human:sam
+kind: verdict
+result: changes_requested
+---
+
+Keep the strip for whitespace only.
+```
+
+Read an issue and its whole history with one command:
+
+```sh
+cat issues/*/*-7k2x9m.md comments/7k2x9m/*.md
+```
+
+Find what the board says about a file before you touch it:
+
+```sh
+grep -rl -- 'src/LoginForm.svelte' .     # or: oifmd about src/LoginForm.svelte
+```
+
+Not everything has a lifecycle. A standalone comment records a judgement
+with no work attached, at `comments/<id>.md`:
+
+```markdown
+---
+type: comment
+at: 2026-09-15T04:10:00Z
+by: human:sam
+kind: confirms
+about:
+  - path: docs/orders.md
+    commit: 3f9c2e1
+---
+
+Checked against the billing code at this commit. Holds.
+```
+
+## Install
+
+The format needs no tool. The validator is there when you want the
+conformance list in section 8 of the spec checked for you.
+
+```sh
+pip install oifmd
+
+oifmd validate <board>      # check a board against the spec
+oifmd about <path>          # what the board says about a file
+oifmd new <board> todo "…"  # create an issue with a fresh id
+```
+
+## Why
+
+Several tools got here first and independently reached the same shape:
+Markdown plus frontmatter, one file per issue, living in the repo.
+[Backlog.md](https://github.com/MrLesk/Backlog.md),
+[beads](https://github.com/steveyegge/beads),
+[git-issues](https://steviee.github.io/git-issues/) and
+[beaver-backlog](https://github.com/builtbystef/beaver-backlog) each
+worked it out on their own, and OIF is built on what they demonstrated.
+
+What is missing is the format itself, written down apart from any one
+tool: a specification you can implement against, a validator that says
+whether a board conforms, and a version number so it can change without
+breaking readers. That is what this is. Issues outlive whichever tool
+wrote them, and any agent can read a board cold.
+
+Design rules that fall out of being agent-first and git-native:
+
+- **State is the directory.** A move is one atomic rename, not a
+  read-modify-write that two agents can trample.
+- **Identity is a random six-character id in the filename.** Two
+  branches can create issues at once and merge with no counter, no
+  scan, no renumbering. Sequential keys like `APP-2753` survive as
+  aliases.
+- **Records point at things; things never point back.** Everything is
+  written under the board root, so a board can describe a vendored
+  dependency, a submodule, a generated tree or a repo you only cloned to
+  review. The target's own tooling sees no diff.
+- **One comment is one file**, keyed by the issue's id. Two agents
+  commenting at once write two different paths, so nothing conflicts and
+  nothing is lost. Appending to a shared file does not survive concurrent
+  writers; see SPEC.md section 7.1.
+- **Unknown keys pass through.** A conforming consumer never rejects
+  them and keeps them when it rewrites a file.
+- **Every column has a `column.md`.** It keeps empty columns in git and
+  tells an arriving agent what belongs there and how to leave.
+- **The board declares its own vocabulary.** `board.md` lists the columns
+  and, optionally, the `kinds` an issue may have and which kinds may
+  contain which. Epic, story and task are one team's words, not the
+  format's. Ready `board.md` files for Kanban, Scrum and Shape Up are in
+  [`profiles/`](https://github.com/oifmd/oifmd/blob/main/profiles).
+
+An OIF board is a conforming [Open Knowledge Format](https://okf.md)
+bundle: same substrate, same actor convention, `type: issue` on every
+file. The one deliberate divergence, identity by id rather than by path,
+is spelled out in SPEC.md section 9. A tracker is a service you log into; OIF is a
+directory you already have.
+
+## This repository
+
+The roadmap for OIF itself lives in [`board/`](https://github.com/oifmd/oifmd/blob/main/board), in OIF.
+GitHub Issues stays open for conversation; accepted work lands in
+`board/issues/` with the GitHub number kept in `external_ids`.
+
+
+## License
+
+Apache-2.0.
+
+Open Issue Format is an independent specification, not affiliated with
+or endorsed by Google. Open Knowledge Format, OKF and Google are marks
+of their respective owners. See SPEC.md section 10.

oifmd-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oifmd"
+version = "0.1.0.dev1"
+description = "Open Issue Format (OIF) validator and tools"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["oif", "issues", "issue-tracker", "markdown", "frontmatter", "okf", "git", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Bug Tracking",
+  "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = ["pyyaml>=6"]
+
+[project.urls]
+Documentation = "https://oif.md/SPEC.md"
+Changelog = "https://github.com/oifmd/oifmd/blob/main/CHANGELOG.md"
+Homepage = "https://oif.md"
+Source = "https://github.com/oifmd/oifmd"
+
+[project.scripts]
+oifmd = "oifmd.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

oifmd-0.1.0.dev1/src/oifmd/__init__.py

@@ -0,0 +1,7 @@
+"""Open Issue Format (OIF) reference tooling. Spec: https://oif.md"""
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("oifmd")
+except PackageNotFoundError:          # running from a source tree, not installed
+    __version__ = "0+unknown"