markback 0.2.1__tar.gz → 0.3.1__tar.gz

{markback-0.2.1 → markback-0.3.1}/.gitignore

@@ -208,8 +208,22 @@ cython_debug/
 node_modules/
 packages/markback/dist/
 packages/markback/*.tsbuildinfo
+packages/markback-vscode/.vscode-test/
+packages/markback-vscode/dist/
+packages/markback-vscode/*.vsix
+
+# Track the internal markbackjs lib's build output (overrides the blanket
+# `dist/` rule above). The VS Code extension consumes markbackjs as a file:
+# dependency via its dist, so committing it keeps a fresh checkout's type
+# resolution and bundle correct without a separate per-consumer build step.
+!packages/markbackjs/dist/
+!packages/markbackjs/dist/**
+packages/markbackjs/dist/*.map
+packages/markbackjs/dist/**/*.map
 
 # Marimo
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+# Local agent/tooling state — never commit
+.claude/

{markback-0.2.1 → markback-0.3.1}/.ishipped/card.md

@@ -1,8 +1,9 @@
 ---
-title: "MarkBack"
+title: "Markback"
 summary: "Human-writable format for pairing content with labels and feedback."
 shipped: 2026-01-04
 theme: forest
+icon: markback-icon.png
 tags: [data-annotation, machine-learning, cli, python, typescript]
 links:
   - label: "markback.org"
@@ -16,7 +17,7 @@ links:
 
 ## What is it?
 
-MarkBack is a compact file format for storing content alongside feedback and labels. It's built for training data management, prompt engineering, and annotation workflows where you need human-readable files that machines can parse reliably.
+Markback is a compact file format for storing content alongside feedback and labels. It's built for training data management, prompt engineering, and annotation workflows where you need human-readable files that machines can parse reliably.
 
 ## Key Features
 

markback-0.3.1/AGENTS.md

@@ -0,0 +1,213 @@
+# Writing Markback (.mb) files
+
+Markback pairs content with single-line feedback using `<<<` as the delimiter.
+
+This is the quickstart. For the full read/write manual — including the traps
+that cost real time — load `skills/markback/SKILL.md`. `SPEC.md` is the
+authority.
+
+## Minimal record
+
+```
+Some content here.
+<<< positive
+```
+
+## Record with headers
+
+```
+@id item-001
+@by reviewer@example.com
+@file ./file.txt
+@input ./prompt.txt
+@tag review p1
+
+Inline content goes here.
+<<< good; quality=high
+```
+
+Headers: `@id`, `@reply-to`, `@by`, `@action`, `@tag`, `@input`, `@file`. All
+optional, and that is also their canonical order.
+
+## Rules
+
+- `<<<` must be followed by one space then feedback text
+- a blank line is **required** between headers and inline content — omit it and
+  a content line starting with `@` is parsed as a header, and the content is
+  silently dropped
+- `@file` + inline content can coexist (file is provenance, content is snapshot)
+- full records are separated by `---`, written directly after the preceding
+  `<<<` line with no blank line before it
+- files must be UTF-8 with LF line endings
+- `@id` values are plain strings (no URI validation)
+
+## Compact format (one record per line)
+
+```
+@file ./images/001.jpg <<< approved; scene=beach
+@file ./images/002.jpg <<< rejected; too dark
+```
+
+No `---` separator needed between compact records. `@id` can go on the line above:
+
+```
+@id item-001
+@file ./file.txt <<< good
+```
+
+Do not leave a blank line before those headers — in 0.3.0 that makes the parser
+discard the record's own `@id`, `@by`, and `@tag` and inherit the previous
+record's instead ([#15](https://github.com/dandriscoll/markback/issues/15)).
+Pack compact records together, or separate them with `---`.
+
+## Multi-record file
+
+```
+@id first
+
+First content.
+<<< positive
+---
+@id second
+
+Second content.
+<<< negative; needs work
+```
+
+## Multi-segment section
+
+Several comments on one source, without repeating the headers. Write successive
+content + `<<<` pairs with no `---` between them; the first segment's `@file`,
+`@by`, `@tag`, and `@input` carry to the rest.
+
+```
+@file ./essay.txt
+@by dan
+
+the lazy fox
+<<< awkward
+
+weak ending
+<<< needs punch
+```
+
+That is two records, both on `./essay.txt`. A `---` ends the section. `@id`,
+`@reply-to`, and `@action` are per-record and never inherited.
+
+## File-level headers (% prefix)
+
+```
+%markback 2
+%scope issue-A issue-B
+%covers ./gen/batch3/*.txt
+
+@file ./gen/batch3/file2.txt <<< issue-B; tone is off
+```
+
+- `%markback 2` — version declaration
+- `%scope` — what issues are being checked (sweep pattern)
+- `%covers` — glob of all files reviewed (absence = clean for scope)
+
+All `%` lines go at the very top, before any record.
+
+## Tags
+
+```
+@id item-001
+@tag training positive-examples batch-2024-03
+@file ./data/example.txt
+<<< approved
+```
+
+Space-separated. Multiple `@tag` lines merge.
+
+## Threading and lifecycle
+
+`@reply-to` carries the `@id` of the record being replied to:
+
+```
+@id c1
+@file ./login.py:42 <<< this branch never fires
+---
+@id c2
+@reply-to c1
+@file ./login.py:42 <<< it does — covered by test_login_edge()
+```
+
+`@action <verb> <timestamp> [actor]` records a lifecycle event. Repeatable and
+order-preserving; the well-known verbs are `created`, `viewed`, `resolved`,
+`reopened`.
+
+```
+@action created 2026-06-17T10:00:00Z dan@example.com
+@action resolved 2026-06-18T14:30:00Z Reviewer Two
+```
+
+A record is resolved when its most recent `resolved`/`reopened` action is
+`resolved`.
+
+## Feedback format
+
+Feedback is freeform text. Optional structured convention:
+
+| Pattern | Meaning |
+|---------|---------|
+| `<<< positive` | label |
+| `<<< negative; too vague` | label + comment |
+| `<<< good; quality=high` | label + attribute |
+| `<<< quality=high; confidence=0.9` | attributes only |
+| `<<< json:{"key":"value"}` | JSON mode |
+
+Segments are separated by `; ` (semicolon + space). Segments with `=` are key-value attributes; without are labels or comments.
+
+## Multi-line feedback
+
+When the text right after `<<< ` is exactly `"""`, the feedback runs until a
+line whose only content is `"""`:
+
+```
+@id c1
+@file ./login.py:42
+<<< """
+This branch looks dead, but I want to double-check before
+suggesting removal.
+"""
+```
+
+Use it only when the feedback genuinely contains a newline.
+
+## Sidecar files
+
+Content in `name.ext`, annotation in `name.ext.mb`:
+
+**report.pdf** — the content
+**report.pdf.mb:**
+```
+@id report-001
+<<< good; grade=B+
+```
+
+## Line/character ranges
+
+`@file` and `@input` support position references:
+
+```
+@file ./code.py:42          ← line 42
+@file ./code.py:42-50       ← lines 42–50
+@file ./code.py:10:5-15:20  ← line 10 col 5 to line 15 col 20
+```
+
+## V1 backward compatibility
+
+V1 headers (`@uri`, `@source`, `@prior`) are automatically mapped to V2 (`@id`, `@file`, `@input`) with a W010 warning.
+
+## Quick checklist
+
+- [ ] every record has exactly one `<<<` line
+- [ ] feedback is a single line, or fenced with `"""`
+- [ ] blank line before inline content
+- [ ] `---` between full records, no blank line before it; not needed between compact records
+- [ ] file ends with a newline
+
+Validate with `mb --lint file.mb`. Add `--no-canonical-check` if the file has
+`%` headers — W008 always fires on those.

{markback-0.2.1 → markback-0.3.1}/IMPLEMENTATION_NOTES.md

@@ -1,4 +1,4 @@
-# Implementation Notes — MarkBack V2
+# Implementation Notes — Markback V2
 
 ## V1 → V2 Changes
 
@@ -15,9 +15,9 @@
 - Sidecar convention simplified to `name.ext.mb` only
 
 ### Removed
-- LLM workflow layer (`llm.py`, `workflow.py`) — not core to MarkBack
+- LLM workflow layer (`llm.py`, `workflow.py`) — not core to Markback
 - `httpx` dependency
-- `config.py` / `python-dotenv` dependency / `--init` command — not core to MarkBack
+- `config.py` / `python-dotenv` dependency / `--init` command — not core to Markback
 - RFC 3986 URI validation on `@id`
 - E003 (malformed URI) no longer emitted
 - E005 (content with @source) no longer emitted — coexistence is valid

{markback-0.2.1 → markback-0.3.1}/PKG-INFO

@@ -1,15 +1,15 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.2.1
-Summary: A compact, human-writable format for storing content paired with feedback/labels
-Project-URL: Homepage, https://github.com/dandriscoll/markback
+Version: 0.3.1
+Summary: Markback — comments for anything, in plain text, in git.
+Project-URL: Homepage, https://markback.org
 Project-URL: Repository, https://github.com/dandriscoll/markback
-Project-URL: Documentation, https://github.com/dandriscoll/markback#readme
+Project-URL: Documentation, https://markback.org/format/spec
 Project-URL: Issues, https://github.com/dandriscoll/markback/issues
 Author: Dan Driscoll
 License-Expression: MIT
 License-File: LICENSE
-Keywords: annotation,data-labeling,feedback,labeling,llm,markdown
+Keywords: annotation,data-labeling,evaluation,feedback,labeling,linter,llm,markdown,prompt-engineering
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -31,9 +31,26 @@ Requires-Dist: pytest>=7.0.0; extra == 'dev'
 Requires-Dist: twine>=5.0.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# MarkBack V2
+# Markback
 
-A compact, human-writable format for storing content paired with feedback/labels.
+> **Comments for anything. In plain text. In git.**
+
+[![PyPI](https://img.shields.io/pypi/v/markback.svg)](https://pypi.org/project/markback/)
+[![npm](https://img.shields.io/npm/v/markbackjs.svg)](https://www.npmjs.com/package/markbackjs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+Markback is a tiny text format for leaving feedback on any file —
+text, code, images, PDFs — that lints, diffs, and lives next to the
+work. CLI, Python, Node, a browser editor, and a VS Code extension.
+
+## Start here
+
+- **Try it without installing** — [markback.org/try-it](https://markback.org/try-it)
+- **Install the CLI** — `pip install markback` or `npm install markbackjs`
+- **Read the format** — [Specification](https://markback.org/format/spec)
+- **Comment from your editor** — [VS Code extension](https://marketplace.visualstudio.com/items?itemName=dandriscoll.markback-vscode)
+- **Point your coding agent at it** — [`skills/markback`](skills/markback/SKILL.md)
 
 ## Installation
 
@@ -41,9 +58,9 @@ A compact, human-writable format for storing content paired with feedback/labels
 pip install -e .
 ```
 
-## Quick Start
+## Quick start
 
-### Parse a MarkBack file
+### Parse a Markback file
 
 ```python
 from markback import parse_file, parse_string
@@ -63,7 +80,7 @@ Some content here.
 result = parse_string(text)
 ```
 
-### Write MarkBack files
+### Write Markback files
 
 ```python
 from markback import Record, FileRef, write, append
@@ -90,7 +107,7 @@ if result.has_errors:
         print(d)
 ```
 
-## CLI Usage
+## CLI usage
 
 The CLI is available via `markback` or `mb` (shorthand).
 
@@ -162,18 +179,22 @@ mb --upgrade *.mb              # preview
 mb --upgrade --apply --in-place *.mb  # apply
 ```
 
-## File Format
+## File format
 
-### V2 Headers
+### Headers
 
 | Header | Purpose |
 |--------|---------|
 | `@id` | Record identifier (plain string) |
+| `@reply-to` | The `@id` this record replies to |
 | `@by` | Who provided feedback |
+| `@action` | `<verb> <timestamp> [actor]` lifecycle event; repeatable |
 | `@tag` | Space-separated tags |
 | `@input` | What produced the content (e.g., a prompt) |
 | `@file` | Path to the content being annotated |
 
+Listed in canonical order. All are optional.
+
 ### File-level headers (% prefix)
 
 ```
@@ -200,6 +221,49 @@ mb --upgrade --apply --in-place *.mb  # apply
 @file ./images/002.jpg <<< rejected; too dark
 ```
 
+### Multi-segment section
+
+Several comments on one source, without repeating the headers — write
+successive content + `<<<` pairs with no `---` between them:
+
+```
+@file ./essay.txt
+
+the lazy fox
+<<< awkward
+
+weak ending
+<<< needs punch
+```
+
+Two records, both on `./essay.txt`. A `---` ends the section.
+
+### Threading and lifecycle
+
+```
+@id c1
+@action created 2026-06-17T10:00:00Z dan@example.com
+@file ./login.py:42 <<< this branch never fires
+---
+@id c2
+@reply-to c1
+@file ./login.py:42 <<< it does — covered by test_login_edge()
+```
+
+### Multi-line feedback
+
+When the text right after `<<< ` is exactly `"""`, feedback runs until a line
+whose only content is `"""`:
+
+```
+@id c1
+@file ./login.py:42
+<<< """
+This branch looks dead, but I want to double-check before
+suggesting removal.
+"""
+```
+
 ### Sidecar files
 
 Content in `report.pdf`, annotation in `report.pdf.mb`:
@@ -224,7 +288,7 @@ Track issues across batches with meaningful absence:
 
 Files matching `%covers` without annotations are implicitly clean for all `%scope` items.
 
-## V1 Backward Compatibility
+## V1 backward compatibility
 
 V1 headers (`@uri`, `@source`, `@prior`) are automatically mapped to V2 equivalents with a W010 warning. The V2 parser reads V1 files transparently.
 

{markback-0.2.1 → markback-0.3.1}/README.md

@@ -1,6 +1,23 @@
-# MarkBack V2
+# Markback
 
-A compact, human-writable format for storing content paired with feedback/labels.
+> **Comments for anything. In plain text. In git.**
+
+[![PyPI](https://img.shields.io/pypi/v/markback.svg)](https://pypi.org/project/markback/)
+[![npm](https://img.shields.io/npm/v/markbackjs.svg)](https://www.npmjs.com/package/markbackjs)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+Markback is a tiny text format for leaving feedback on any file —
+text, code, images, PDFs — that lints, diffs, and lives next to the
+work. CLI, Python, Node, a browser editor, and a VS Code extension.
+
+## Start here
+
+- **Try it without installing** — [markback.org/try-it](https://markback.org/try-it)
+- **Install the CLI** — `pip install markback` or `npm install markbackjs`
+- **Read the format** — [Specification](https://markback.org/format/spec)
+- **Comment from your editor** — [VS Code extension](https://marketplace.visualstudio.com/items?itemName=dandriscoll.markback-vscode)
+- **Point your coding agent at it** — [`skills/markback`](skills/markback/SKILL.md)
 
 ## Installation
 
@@ -8,9 +25,9 @@ A compact, human-writable format for storing content paired with feedback/labels
 pip install -e .
 ```
 
-## Quick Start
+## Quick start
 
-### Parse a MarkBack file
+### Parse a Markback file
 
 ```python
 from markback import parse_file, parse_string
@@ -30,7 +47,7 @@ Some content here.
 result = parse_string(text)
 ```
 
-### Write MarkBack files
+### Write Markback files
 
 ```python
 from markback import Record, FileRef, write, append
@@ -57,7 +74,7 @@ if result.has_errors:
         print(d)
 ```
 
-## CLI Usage
+## CLI usage
 
 The CLI is available via `markback` or `mb` (shorthand).
 
@@ -129,18 +146,22 @@ mb --upgrade *.mb              # preview
 mb --upgrade --apply --in-place *.mb  # apply
 ```
 
-## File Format
+## File format
 
-### V2 Headers
+### Headers
 
 | Header | Purpose |
 |--------|---------|
 | `@id` | Record identifier (plain string) |
+| `@reply-to` | The `@id` this record replies to |
 | `@by` | Who provided feedback |
+| `@action` | `<verb> <timestamp> [actor]` lifecycle event; repeatable |
 | `@tag` | Space-separated tags |
 | `@input` | What produced the content (e.g., a prompt) |
 | `@file` | Path to the content being annotated |
 
+Listed in canonical order. All are optional.
+
 ### File-level headers (% prefix)
 
 ```
@@ -167,6 +188,49 @@ mb --upgrade --apply --in-place *.mb  # apply
 @file ./images/002.jpg <<< rejected; too dark
 ```
 
+### Multi-segment section
+
+Several comments on one source, without repeating the headers — write
+successive content + `<<<` pairs with no `---` between them:
+
+```
+@file ./essay.txt
+
+the lazy fox
+<<< awkward
+
+weak ending
+<<< needs punch
+```
+
+Two records, both on `./essay.txt`. A `---` ends the section.
+
+### Threading and lifecycle
+
+```
+@id c1
+@action created 2026-06-17T10:00:00Z dan@example.com
+@file ./login.py:42 <<< this branch never fires
+---
+@id c2
+@reply-to c1
+@file ./login.py:42 <<< it does — covered by test_login_edge()
+```
+
+### Multi-line feedback
+
+When the text right after `<<< ` is exactly `"""`, feedback runs until a line
+whose only content is `"""`:
+
+```
+@id c1
+@file ./login.py:42
+<<< """
+This branch looks dead, but I want to double-check before
+suggesting removal.
+"""
+```
+
 ### Sidecar files
 
 Content in `report.pdf`, annotation in `report.pdf.mb`:
@@ -191,7 +255,7 @@ Track issues across batches with meaningful absence:
 
 Files matching `%covers` without annotations are implicitly clean for all `%scope` items.
 
-## V1 Backward Compatibility
+## V1 backward compatibility
 
 V1 headers (`@uri`, `@source`, `@prior`) are automatically mapped to V2 equivalents with a W010 warning. The V2 parser reads V1 files transparently.