markback 0.3.0__tar.gz → 0.3.1__tar.gz

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.3.0 → markback-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markback
-Version: 0.3.0
+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
@@ -49,7 +49,8 @@ work. CLI, Python, Node, a browser editor, and a VS Code extension.
 - **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 v0.1](https://github.com/dandriscoll/markback/tree/main/packages/markback-vscode)
+- **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
 
@@ -57,7 +58,7 @@ work. CLI, Python, Node, a browser editor, and a VS Code extension.
 pip install -e .
 ```
 
-## Quick Start
+## Quick start
 
 ### Parse a Markback file
 
@@ -106,7 +107,7 @@ if result.has_errors:
         print(d)
 ```
 
-## CLI Usage
+## CLI usage
 
 The CLI is available via `markback` or `mb` (shorthand).
 
@@ -178,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)
 
 ```
@@ -216,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`:
@@ -240,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.3.0 → markback-0.3.1}/README.md

@@ -16,7 +16,8 @@ work. CLI, Python, Node, a browser editor, and a VS Code extension.
 - **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 v0.1](https://github.com/dandriscoll/markback/tree/main/packages/markback-vscode)
+- **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
 
@@ -24,7 +25,7 @@ work. CLI, Python, Node, a browser editor, and a VS Code extension.
 pip install -e .
 ```
 
-## Quick Start
+## Quick start
 
 ### Parse a Markback file
 
@@ -73,7 +74,7 @@ if result.has_errors:
         print(d)
 ```
 
-## CLI Usage
+## CLI usage
 
 The CLI is available via `markback` or `mb` (shorthand).
 
@@ -145,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)
 
 ```
@@ -183,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`:
@@ -207,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.
 

{markback-0.3.0 → markback-0.3.1}/SPEC.md

@@ -1253,18 +1253,18 @@ full-record       = [headers] [content-block] feedback-line
 headers           = 1*header-line
 header-line       = "@" keyword SP value LF
 keyword           = 1*LOWER
-value             = *VCHAR
+value             = *(VCHAR / SP)                    ; freeform; may contain interior spaces; ends at LF
 
 content-block     = blank-line content
 content           = 1*content-line
-content-line      = *VCHAR LF                       ; any line not starting with <<<
+content-line      = *(VCHAR / SP) LF                 ; any line not starting with <<<
 
 blank-line        = LF
 
 ; === Feedback ===
 
 feedback-line     = "<<<" SP feedback-content LF
-feedback-content  = *VCHAR                           ; no LF allowed
+feedback-content  = *(VCHAR / SP)                    ; freeform; no LF allowed
 
 ; === Compact Record ===
 

markback-0.3.1/markback/_headers.py

@@ -0,0 +1,14 @@
+"""DO NOT EDIT — generated from shared/headers.json by scripts/gen_headers.py."""
+
+# Header keywords the parser recognizes (others emit W002).
+KNOWN_HEADERS = set(["id", "by", "file", "input", "tag", "reply-to", "action"])
+
+# The order headers are emitted in canonical output (SPEC §7.1).
+CANONICAL_ORDER = ["id", "reply-to", "by", "action", "tag", "input", "file"]
+
+# Headers inherited by continuation segments of a multi-segment section
+# (@id, @reply-to, and @action are per-record and never inherited).
+SECTION_INHERITED = set(["file", "by", "tag", "input"])
+
+# V1 header names mapped to their V2 equivalents (each emits W010).
+V1_HEADER_MAP = {"uri": "id", "source": "file", "prior": "input"}

{markback-0.3.0 → markback-0.3.1}/markback/linter.py

@@ -248,11 +248,22 @@ def lint_canonical_format(
     records: list[Record],
     original_text: str,
     file: Optional[Path],
+    scope: Optional[list[str]] = None,
+    covers: Optional[str] = None,
+    version: Optional[int] = None,
 ) -> list[Diagnostic]:
     """Check if file is in canonical format."""
     diagnostics: list[Diagnostic] = []
 
-    canonical = write_string(records, version_header=False)
+    # The comparison render must carry the file's own %-headers, otherwise any
+    # canonical file with %markback/%scope/%covers mismatches and reports a
+    # false W008. version_header is on iff the file declared a %markback line.
+    canonical = write_string(
+        records,
+        scope=scope,
+        covers=covers,
+        version_header=version is not None,
+    )
     original_normalized = original_text.replace('\r\n', '\n').replace('\r', '\n')
 
     if original_normalized != canonical:
@@ -307,6 +318,9 @@ def lint_string(
             result.records,
             text,
             source_file,
+            scope=result.scope,
+            covers=result.covers,
+            version=result.version,
         ))
 
     return result

{markback-0.3.0 → markback-0.3.1}/markback/parser.py

@@ -4,6 +4,7 @@ import re
 from pathlib import Path
 from typing import Optional
 
+from ._headers import KNOWN_HEADERS, SECTION_INHERITED, V1_HEADER_MAP
 from .types import (
     Action,
     Diagnostic,
@@ -15,13 +16,6 @@ from .types import (
     WarningCode,
 )
 
-
-# V2 known header keywords
-KNOWN_HEADERS = {"id", "by", "file", "input", "tag", "reply-to", "action"}
-
-# V1 header mapping for backward compatibility
-V1_HEADER_MAP = {"uri": "id", "source": "file", "prior": "input"}
-
 # Patterns
 HEADER_PATTERN = re.compile(r"^@([a-z][a-z-]*)\s+(.+)$")
 FEEDBACK_DELIMITER = "<<<"
@@ -192,21 +186,22 @@ def parse_string(
     had_blank_line: bool = False
     past_file_headers: bool = False
 
-    SECTION_INHERITED = ("file", "by", "tag", "input")
-
     def finalize_record(feedback: str, end_line: int):
         """Create a record from current state, then reset for next segment."""
         nonlocal current_headers, current_actions, current_content_lines, current_start_line
         nonlocal pending_id, in_content, had_blank_line, section_headers
 
+        # Section-inherited headers (@file, @by, @tag, @input) fall back to the
+        # section value only when this segment did not declare its own. @id and
+        # @reply-to are per-record and never inherited.
         record_id = current_headers.get("id") or pending_id
-        by = current_headers.get("by")
+        by = current_headers.get("by") or section_headers.get("by")
         reply_to = current_headers.get("reply-to")
-        file_str = current_headers.get("file")
+        file_str = current_headers.get("file") or section_headers.get("file")
         file_ref = FileRef(file_str) if file_str else None
-        input_str = current_headers.get("input")
+        input_str = current_headers.get("input") or section_headers.get("input")
         input_ref = FileRef(input_str) if input_str else None
-        tag_str = current_headers.get("tag")
+        tag_str = current_headers.get("tag") or section_headers.get("tag")
         tags = tag_str.split() if tag_str else []
 
         content = None
@@ -243,8 +238,12 @@ def parse_string(
                 if k in SECTION_INHERITED
             }
 
-        # Reset state for the next segment, inheriting section headers.
-        current_headers = section_headers.copy()
+        # Reset state for the next segment. current_headers holds only what the
+        # NEXT segment declares itself; inherited values live in section_headers
+        # and are merged in at finalize. Starting empty (rather than a copy of
+        # section_headers) is what lets a blank line between records read as a
+        # record separator, and a re-declared @tag override rather than merge.
+        current_headers = {}
         current_actions = []
         current_content_lines = []
         current_start_line = end_line + 1
@@ -312,7 +311,7 @@ def parse_string(
         if line_type == LineType.SEPARATOR:
             # `---` ends the section: clear inheritable headers entirely.
             # Error only if user added headers/content since last finalize.
-            if current_content_lines or current_headers != section_headers:
+            if current_content_lines or current_headers:
                 add_diagnostic(
                     Severity.ERROR,
                     ErrorCode.E001,
@@ -330,10 +329,15 @@ def parse_string(
             continue
 
         if line_type == LineType.BLANK:
-            if current_headers and not in_content:
-                had_blank_line = True
-            elif in_content:
+            if in_content:
                 current_content_lines.append("")
+            elif current_headers:
+                # A blank AFTER this segment's own headers is the
+                # header/content separator (§3.2.1). A blank when the segment
+                # has declared no headers of its own is a between-records
+                # separator and is ignored (§3.5) — so the next @-lines are
+                # read as the following record's headers, not as content.
+                had_blank_line = True
             continue
 
         if line_type == LineType.COMPACT_RECORD:
@@ -383,11 +387,11 @@ def parse_string(
                 )
 
             record_id = pending_id or current_headers.get("id")
-            by = current_headers.get("by")
+            by = current_headers.get("by") or section_headers.get("by")
             reply_to = current_headers.get("reply-to")
-            input_str = current_headers.get("input")
+            input_str = current_headers.get("input") or section_headers.get("input")
             input_ref = FileRef(input_str) if input_str else None
-            tag_str = current_headers.get("tag")
+            tag_str = current_headers.get("tag") or section_headers.get("tag")
             tags = tag_str.split() if tag_str else []
 
             record = Record(
@@ -415,7 +419,7 @@ def parse_string(
                 }
                 # The compact line itself supplied @file:
                 section_headers["file"] = str(file_ref)
-            current_headers = section_headers.copy()
+            current_headers = {}
             current_actions = []
             current_content_lines = []
             current_start_line = end_line + 1
@@ -539,7 +543,7 @@ def parse_string(
             continue
 
     # Check for unterminated record at end of file
-    if current_content_lines or current_headers != section_headers:
+    if current_content_lines or current_headers:
         add_diagnostic(
             Severity.ERROR,
             ErrorCode.E001,