sessionmemory 0.3.1__tar.gz → 0.4.1__tar.gz

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sessionmemory
-Version: 0.3.1
+Version: 0.4.1
 Summary: Durable memory for coding agents, one folder of searchable pages per project.
 Author: Nathaniel Landau
 Author-email: Nathaniel Landau <github@natelandau.com>
@@ -215,8 +215,11 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
   - Past sessions, one page each: `sessionmemory search "<words>" --logs`.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
-    `- [ ] [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add, tick, or
-    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+    `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with
+    `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
+    which creates the file or heading when missing. Delete a finished line, and one
+    that will never be done, directly; never tick or annotate it. Git history is the
+    record of what was finished.
   - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file
     and prints its path. Edit it directly after that.
   - Learnings are captured at session end, not by you mid-session. When the user asks

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/README.md

@@ -200,8 +200,11 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
   - Past sessions, one page each: `sessionmemory search "<words>" --logs`.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
-    `- [ ] [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add, tick, or
-    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+    `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with
+    `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
+    which creates the file or heading when missing. Delete a finished line, and one
+    that will never be done, directly; never tick or annotate it. Git history is the
+    record of what was finished.
   - Specs and plans: `sessionmemory new spec|plan --title "..." --cwd .` creates the file
     and prints its path. Edit it directly after that.
   - Learnings are captured at session end, not by you mid-session. When the user asks

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/pyproject.toml

@@ -11,7 +11,7 @@ description = "Durable memory for coding agents, one folder of searchable pages
 name = "sessionmemory"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
-version = "0.3.1"
+version = "0.4.1"
 
 [[project.authors]]
 name = "Nathaniel Landau"

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/pyproject.toml.orig

@@ -12,7 +12,7 @@
     name = "sessionmemory"
     readme = "README.md"
     requires-python = ">=3.13,<3.15"
-    version = "0.3.1"
+    version = "0.4.1"
 
     [project.scripts]
         sessionmemory = "sessionmemory.cli:main"

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/commands/new.py

@@ -1,7 +1,8 @@
-"""Commands that create a page or a document and print the path to write into."""
+"""Commands that create a page, a document, or a backlog item and print what was written."""
 
 from __future__ import annotations
 
+import enum
 from pathlib import Path  # noqa: TC003
 
 import typer
@@ -14,10 +15,15 @@ from sessionmemory.commands._common import (
     require_vault,
     resolve_body,
 )
-from sessionmemory.lib import field, paths
-from sessionmemory.lib.config import now
+from sessionmemory.lib import backlog, field, paths
+from sessionmemory.lib.config import now, today
 
-app = typer.Typer(no_args_is_help=True, help="Create a learning, spec, or plan.")
+app = typer.Typer(no_args_is_help=True, help="Create a learning, spec, plan, or backlog item.")
+
+# Typer lists an Enum's members in --help and rejects anything else at parse time, so the
+# allowed sets are spelled once, in lib/backlog, and mirrored here as choices.
+Kind = enum.Enum("Kind", {kind: kind for kind in backlog.KINDS}, type=str)
+Size = enum.Enum("Size", {size: size for size in backlog.SIZES}, type=str)
 
 TITLE = typer.Option(..., "--title", help="The title.")
 SUMMARY = typer.Option(..., "--summary", help="One sentence a search result shows.")
@@ -25,6 +31,10 @@ BODY = typer.Option("", "--body", help="Markdown body.")
 BODY_FILE = typer.Option(None, "--body-file", help="Read the body from a file, or stdin for '-'.")
 CWD = typer.Option(None, "--cwd", help="Directory to resolve the project from.")
 JSON = typer.Option(False, "--json", help="Emit JSON instead of prose.")  # noqa: FBT003
+KIND = typer.Option(..., "--kind", help="The commit type heading the item goes under.")
+SIZE = typer.Option(..., "--size", help="Effort: S, M, or L.")
+DESCRIPTION = typer.Option(..., "--title", help="The imperative description of the work.")
+TOPIC = typer.Option(None, "--topic", help="A topic tag, without the leading hash.")
 
 
 def _report(path: Path, *, as_json: bool, uuid: str | None = None) -> None:
@@ -62,7 +72,7 @@ def new_learning(
 
 def _new_document(folder: Path, title: str, body: str, *, as_json: bool) -> None:
     try:
-        path = field.new_document(folder, title=title, body=body, now=now())
+        path = field.new_document(folder, title=title, body=body, now=now(), day=today())
     except field.PageError as error:
         fail(str(error))
     _report(path, as_json=as_json)
@@ -100,3 +110,33 @@ def new_plan(
     _new_document(
         paths.plans_dir(vault, slug), title, resolve_body(body, body_file), as_json=as_json
     )
+
+
+@app.command("backlog", help="Add one open item to this project's backlog.md.")
+def new_backlog(
+    kind: Kind = KIND,
+    size: Size = SIZE,
+    title: str = DESCRIPTION,
+    topic: str | None = TOPIC,
+    cwd: Path | None = CWD,
+    *,
+    as_json: bool = JSON,
+) -> None:
+    """Append an open item under its kind heading, creating the file or heading as needed.
+
+    Raises:
+        typer.Exit: The title or topic cannot be written as a well-formed line.
+    """
+    vault = require_vault()
+    slug = require_project(vault, cwd)
+    path = paths.backlog_path(vault, slug)
+    try:
+        line = backlog.add_item(
+            path, kind=kind.value, size=size.value, description=title, topic=topic, today=today()
+        )
+    except backlog.BacklogError as error:
+        fail(str(error))
+    if as_json:
+        emit_json({"path": str(path), "line": line})
+        return
+    pp.success(f"added to {path.name}", details=[line, str(path)])

sessionmemory-0.4.1/src/sessionmemory/lib/backlog.py

@@ -0,0 +1,134 @@
+"""Append an item to a project's backlog and recognize one.
+
+This is the one place the item line's shape is known. A backlog line carries a kind that
+must match a `## <kind>` heading, a size from a fixed set, a date, and a topic tag, and
+the inject count, the doctor check, and the backlog skill all depend on that shape being
+exact. The line has no checkbox: finished work is deleted, and git history is the
+record of it, so there is nothing to tick. Deleting a line needs no validation and
+stays a direct edit.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from sessionmemory.lib import atomic
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+KINDS = ("feat", "fix", "refactor", "perf", "docs", "test", "build", "ci")
+SIZES = ("S", "M", "L")
+HEADING = "# Backlog"
+ITEM_PATTERN = re.compile(
+    rf"^- \[(?:{'|'.join(SIZES)})\] \S.* - \d{{4}}-\d{{2}}-\d{{2}}(?: \[#[^\s\]]+\])?$"
+)
+_SECTION_PREFIX = "## "
+
+
+class BacklogError(ValueError):
+    """An item field that cannot be written as a well-formed line."""
+
+
+def format_item(*, kind: str, size: str, description: str, topic: str | None, today: str) -> str:
+    """Return the checklist line for one open item, validating every field.
+
+    Args:
+        kind (str): One of `KINDS`; the heading the line belongs under.
+        size (str): One of `SIZES`.
+        description (str): The imperative description, a single line.
+        topic (str | None): The tag written as `[#topic]`, or None for no tag. A leading
+            `#` is accepted and dropped.
+        today (str): The date as `YYYY-MM-DD`.
+
+    Returns:
+        str: The line, without a trailing newline.
+
+    Raises:
+        BacklogError: A field is empty, spans lines, contains whitespace where a tag
+            cannot, or names an unknown kind or size.
+    """
+    if kind not in KINDS:
+        msg = f"kind must be one of {', '.join(KINDS)}, not {kind!r}"
+        raise BacklogError(msg)
+    if size not in SIZES:
+        msg = f"size must be one of {', '.join(SIZES)}, not {size!r}"
+        raise BacklogError(msg)
+    description = description.strip()
+    if not description:
+        msg = "the description is empty"
+        raise BacklogError(msg)
+    if "\n" in description:
+        msg = "the description must be a single line"
+        raise BacklogError(msg)
+    line = f"- [{size}] {description} - {today}"
+    if topic is None:
+        return line
+    topic = topic.strip().removeprefix("#")
+    if not topic:
+        msg = "the topic is empty"
+        raise BacklogError(msg)
+    if any(character.isspace() for character in topic):
+        msg = "the topic cannot contain whitespace"
+        raise BacklogError(msg)
+    return f"{line} [#{topic}]"
+
+
+def is_item(line: str) -> bool:
+    """Return whether `line` is an open item, the only shape the session start counts.
+
+    Args:
+        line (str): One line of `backlog.md`; leading whitespace is ignored.
+
+    Returns:
+        bool: True for `- [S|M|L] <description> - <YYYY-MM-DD>` with an optional
+            `[#topic]`, and False for anything else, a checkbox included.
+    """
+    return ITEM_PATTERN.match(line.lstrip()) is not None
+
+
+def _insert(lines: list[str], kind: str, item: str) -> list[str]:
+    """Place `item` at the end of the `## kind` section, or open that section last."""
+    heading = f"{_SECTION_PREFIX}{kind}"
+    start = next((i for i, line in enumerate(lines) if line.rstrip() == heading), None)
+    if start is None:
+        return [*lines, "", heading, "", item]
+    end = next(
+        (i for i in range(start + 1, len(lines)) if lines[i].startswith(_SECTION_PREFIX)),
+        len(lines),
+    )
+    last = end
+    while last > start + 1 and not lines[last - 1].strip():
+        last -= 1
+    if last == start + 1:
+        return [*lines[:last], "", item, *lines[last:]]
+    return [*lines[:last], item, *lines[last:]]
+
+
+def add_item(
+    path: Path, *, kind: str, size: str, description: str, topic: str | None, today: str
+) -> str:
+    """Append one open item under its kind heading and return the line written.
+
+    A missing file starts with `# Backlog`. An existing file keeps whatever heads it,
+    since the `# Backlog` heading is never inserted into a file someone else structured.
+
+    Args:
+        path (Path): The project's `backlog.md`.
+        kind (str): One of `KINDS`.
+        size (str): One of `SIZES`.
+        description (str): The imperative description.
+        topic (str | None): The tag, or None for none.
+        today (str): The date as `YYYY-MM-DD`.
+
+    Returns:
+        str: The line written, without a trailing newline.
+
+    Raises:
+        BacklogError: A field cannot be written as a well-formed line.
+    """
+    item = format_item(kind=kind, size=size, description=description, topic=topic, today=today)
+    lines = path.read_text(encoding="utf-8").rstrip().splitlines() if path.is_file() else [HEADING]
+    atomic.write_text(path, "\n".join(_insert(lines, kind=kind, item=item)) + "\n")
+    return item

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/lib/bootstrap.py

@@ -57,7 +57,8 @@ derived from the pages beside it, gitignored, and rebuilt by `sessionmemory rein
 `_system/vault.toml` is the marker that tells the CLI this directory is a vault.
 
 Pages are created with `sessionmemory new learning` and searched with
-`sessionmemory search`. Everything else is an ordinary file you read and edit directly.
+`sessionmemory search`, and a backlog item is added with `sessionmemory new backlog`.
+Everything else is an ordinary file you read and edit directly.
 The format follows the memoryfield spec: https://github.com/calpaterson/memoryfield-spec
 """
 

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/lib/config.py

@@ -83,12 +83,15 @@ def _configured_root() -> str | None:
 
 
 def today() -> str:
-    """Return today's date as an ISO string.
+    """Return today's local date as an ISO string.
+
+    A date a person reads, in a filename or a checklist line, follows their clock; only
+    the frontmatter timestamps from `now` are UTC, which the memoryfield spec asks for.
 
     Returns:
         str: Today's date.
     """
-    return datetime.datetime.now(tz=datetime.UTC).date().isoformat()
+    return datetime.datetime.now().astimezone().date().isoformat()
 
 
 def now() -> str:

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/lib/doctor.py

@@ -1,4 +1,4 @@
-"""The six things that can be wrong with a vault, stated without severity.
+"""The seven things that can be wrong with a vault, stated without severity.
 
 Every check is a suggestion. The article's argument holds: an irrelevant or imperfect
 page is never surfaced by semantic search, so nothing here fails a build. There is no
@@ -13,7 +13,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-from sessionmemory.lib import field, fieldindex, paths, registry
+from sessionmemory.lib import backlog, field, fieldindex, paths, registry
 from sessionmemory.lib.frontmatter import (
     FrontmatterError,
     MissingFrontmatterError,
@@ -139,6 +139,33 @@ def dead_projects(vault: Path, _embedder: Embedder) -> list[Finding]:
     ]
 
 
+_TICKED = "- [x]"
+_SHAPE = "- [S|M|L] <description> - <YYYY-MM-DD> [#topic]"
+
+
+def uncounted_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
+    """Report a top-level bullet in a backlog that the session start does not count.
+
+    A ticked line is finished work that should have been deleted; anything else is a
+    line that does not match the item shape. An indented bullet is a note under an
+    item and is left alone.
+    """
+    findings = []
+    for slug in paths.iter_project_slugs(vault):
+        path = paths.backlog_path(vault, slug)
+        if not path.is_file():
+            continue
+        for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+            if not line.startswith("- ") or backlog.is_item(line):
+                continue
+            if line.startswith(_TICKED):
+                message = f"line {number}: ticked; finished work is deleted, not ticked"
+            else:
+                message = f"line {number}: not counted as open; the shape is `{_SHAPE}`"
+            findings.append(Finding("backlog", str(path), message))
+    return findings
+
+
 def _is_stale(directory: Path, embedder: Embedder) -> str | None:
     index = fieldindex.index_path(directory, embedder)
     if not index.is_file():
@@ -177,6 +204,7 @@ CHECKS: tuple[Callable[[Path, Embedder], list[Finding]], ...] = (
     malformed_frontmatter,
     unquoted_datetimes,
     dead_projects,
+    uncounted_backlog_lines,
     stale_indexes,
 )
 

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/lib/field.py

@@ -179,21 +179,18 @@ def new_page(directory: Path, *, title: str, summary: str, body: str, now: str)
     return _create(directory, meta, body, stem=None)
 
 
-def new_document(
-    directory: Path, *, title: str, body: str, now: str, stem: str | None = None
-) -> Path:
-    """Create a spec, plan, or log: a titled, dated file that is not a memory page.
+def new_document(directory: Path, *, title: str, body: str, now: str, day: str) -> Path:
+    """Create a spec or plan: a titled, dated file that is not a memory page.
 
-    The filename leads with the creation date unless the caller fixes the stem, so a
-    directory listing reads in the order the documents were written.
+    The filename leads with `day`, so a directory listing reads in the order the
+    documents were written. `day` is passed rather than sliced from `now` because the
+    timestamp is UTC and the date a person reads in a filename follows their own clock.
 
     Raises:
         PageError: If the title yields no slug or no name is free.
     """
-    if stem is None:
-        stem = dated_stem(title, now[: len("2026-01-01")])
     meta = {"title": title, "created": now, "updated": now}
-    return _create(directory, meta, body, stem=stem)
+    return _create(directory, meta, body, stem=dated_stem(title, day))
 
 
 def dated_stem(title: str, day: str) -> str:

{sessionmemory-0.3.1 → sessionmemory-0.4.1}/src/sessionmemory/lib/inject.py

@@ -10,12 +10,11 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from sessionmemory.lib import field, paths
+from sessionmemory.lib import backlog, field, paths
 
 if TYPE_CHECKING:
     from pathlib import Path
 
-OPEN_ITEM = "- [ ]"
 _LEADING_PUNCTUATION = "`'\"([{<*_~"
 
 
@@ -43,11 +42,7 @@ def _titles(directory: Path) -> tuple[str, ...]:
 def _open_backlog(path: Path) -> int:
     if not path.is_file():
         return 0
-    return sum(
-        1
-        for line in path.read_text(encoding="utf-8").splitlines()
-        if line.lstrip().startswith(OPEN_ITEM)
-    )
+    return sum(1 for line in path.read_text(encoding="utf-8").splitlines() if backlog.is_item(line))
 
 
 def build(vault: Path, slug: str) -> Injection:
@@ -76,8 +71,11 @@ away. The project's folder has `learnings/` and `logs/`, searched by meaning, be
   - Past sessions, one page each: `{command} search "<words>" --logs`.
   - Open work: read `backlog.md`. An item is one line under a `## <kind>` heading
     (feat, fix, refactor, perf, docs, test, build, ci), sized S, M, or L:
-    `- [ ] [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add, tick, or
-    delete lines directly. If the file is missing, create it with a `# Backlog` heading.
+    `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`. Add one with
+    `{command} new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
+    which creates the file or heading when missing. Delete a finished line, and one
+    that will never be done, directly; never tick or annotate it. Git history is the
+    record of what was finished.
   - Specs and plans: `{command} new spec|plan --title "..." --cwd .` creates the file
     and prints its path. Edit it directly after that.
   - Learnings are captured at session end, not by you mid-session. When the user asks