sessionmemory 0.18.0__tar.gz → 0.19.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/PKG-INFO +10 -8
  2. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/README.md +7 -5
  3. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/pyproject.toml +13 -13
  4. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/pyproject.toml.orig +13 -13
  5. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/new.py +20 -26
  6. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/backlog.py +135 -15
  7. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/bootstrap.py +3 -2
  8. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/doctor.py +2 -4
  9. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/inject.py +7 -5
  10. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/__init__.py +0 -0
  11. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/cli.py +0 -0
  12. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/__init__.py +0 -0
  13. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/_common.py +0 -0
  14. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/delete.py +0 -0
  15. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/doctor.py +0 -0
  16. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/export.py +0 -0
  17. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/init.py +0 -0
  18. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/inject.py +0 -0
  19. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/local.py +0 -0
  20. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/log.py +0 -0
  21. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/path.py +0 -0
  22. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/project.py +0 -0
  23. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reconcile.py +0 -0
  24. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reindex.py +0 -0
  25. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/search.py +0 -0
  26. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/entry.py +0 -0
  27. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/__init__.py +0 -0
  28. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/atomic.py +0 -0
  29. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/changes.py +0 -0
  30. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/commits.py +0 -0
  31. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/config.py +0 -0
  32. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/embed.py +0 -0
  33. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/export.py +0 -0
  34. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/field.py +0 -0
  35. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  36. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  37. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/gitinfo.py +0 -0
  38. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/ids.py +0 -0
  39. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localdeclined.py +0 -0
  40. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmanifest.py +0 -0
  41. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmd.py +0 -0
  42. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localtree.py +0 -0
  43. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/log.py +0 -0
  44. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/paths.py +0 -0
  45. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/reconcile.py +0 -0
  46. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registration.py +0 -0
  47. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registry.py +0 -0
  48. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/resolve.py +0 -0
  49. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
  50. {sessionmemory-0.18.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/specs.py +0 -0
@@ -1,15 +1,15 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: sessionmemory
3
- Version: 0.18.0
3
+ Version: 0.19.0
4
4
  Summary: Durable memory for coding agents, one folder of searchable pages per project.
5
5
  Author: Nathaniel Landau
6
6
  Author-email: Nathaniel Landau <github@natelandau.com>
7
- Requires-Dist: fastembed>=0.9.0
7
+ Requires-Dist: fastembed>=0.9.1
8
8
  Requires-Dist: nclutils>=4.0.0
9
9
  Requires-Dist: pyyaml>=6.0.3
10
10
  Requires-Dist: sqlite-vec>=0.1.9
11
11
  Requires-Dist: tomli-w>=1.2.0
12
- Requires-Dist: typer>=0.27.3
12
+ Requires-Dist: typer>=0.29.1
13
13
  Requires-Python: >=3.13, <3.15
14
14
  Description-Content-Type: text/markdown
15
15
 
@@ -232,15 +232,17 @@ all for a script.
232
232
  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
233
233
  for why something was decided, what happened the last time an area changed, or
234
234
  whether a fix was already tried.
235
- - Open work: read `backlog.md`. Any top-level bullet is an open item. Under a
235
+ - Open work: read `backlog.md`. Any top-level bullet is an open item, and the
236
+ indented lines under it are its detail. Under a
236
237
  `## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
237
238
  full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
238
239
  Add one with
239
240
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
240
- which writes that shape and creates the file or heading when missing. Questions
241
- for the user to answer go under `## decide`. Delete a finished line, and one
242
- that will never be done, directly; never tick or annotate it. Git history is the
243
- record of what was finished.
241
+ which writes that shape and creates the file or heading when missing. Keep the
242
+ title to one short sentence and pass context (why, where, what was tried) with
243
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
244
+ the user to answer go under `## decide`. Delete a finished item with its detail,
245
+ and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
244
246
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
245
247
  and kept after the work ships. Before designing or changing a feature, search
246
248
  them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
@@ -217,15 +217,17 @@ all for a script.
217
217
  - Past sessions, one page each: `sessionmemory search "<words>" --logs`. Search them
218
218
  for why something was decided, what happened the last time an area changed, or
219
219
  whether a fix was already tried.
220
- - Open work: read `backlog.md`. Any top-level bullet is an open item. Under a
220
+ - Open work: read `backlog.md`. Any top-level bullet is an open item, and the
221
+ indented lines under it are its detail. Under a
221
222
  `## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
222
223
  full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
223
224
  Add one with
224
225
  `sessionmemory new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
225
- which writes that shape and creates the file or heading when missing. Questions
226
- for the user to answer go under `## decide`. Delete a finished line, and one
227
- that will never be done, directly; never tick or annotate it. Git history is the
228
- record of what was finished.
226
+ which writes that shape and creates the file or heading when missing. Keep the
227
+ title to one short sentence and pass context (why, where, what was tried) with
228
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
229
+ the user to answer go under `## decide`. Delete a finished item with its detail,
230
+ and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
229
231
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
230
232
  and kept after the work ships. Before designing or changing a feature, search
231
233
  them: `sessionmemory search "<words>" --specs` (listing the directory works too), so a
@@ -1,17 +1,17 @@
1
1
  [project]
2
2
  dependencies = [
3
- "fastembed>=0.9.0",
3
+ "fastembed>=0.9.1",
4
4
  "nclutils>=4.0.0",
5
5
  "pyyaml>=6.0.3",
6
6
  "sqlite-vec>=0.1.9",
7
7
  "tomli-w>=1.2.0",
8
- "typer>=0.27.3",
8
+ "typer>=0.29.1",
9
9
  ]
10
10
  description = "Durable memory for coding agents, one folder of searchable pages per project."
11
11
  name = "sessionmemory"
12
12
  readme = "README.md"
13
13
  requires-python = ">=3.13,<3.15"
14
- version = "0.18.0"
14
+ version = "0.19.0"
15
15
 
16
16
  [[project.authors]]
17
17
  name = "Nathaniel Landau"
@@ -22,23 +22,23 @@ sessionmemory = "sessionmemory.entry:main"
22
22
 
23
23
  [dependency-groups]
24
24
  dev = [
25
- "commitizen>=4.19.2",
26
- "coverage>=7.16.2",
25
+ "commitizen>=4.19.3",
26
+ "coverage>=7.17.3",
27
27
  "duty>=1.10.1",
28
- "gate-cache>=0.6.0",
29
- "prek>=0.5.5",
28
+ "gate-cache>=0.7.0",
29
+ "prek>=0.5.11",
30
30
  "pytest-clarity>=1.0.1",
31
31
  "pytest-cov>=7.1.0",
32
32
  "pytest-devtools>=1.3.0",
33
- "pytest-mock>=3.16.0",
33
+ "pytest-mock>=3.17.0",
34
34
  "pytest-xdist>=3.8.0",
35
- "pytest>=9.1.1",
35
+ "pytest>=9.2.0",
36
36
  "rich>=15.0.0",
37
- "ruff>=0.17.0",
37
+ "ruff>=0.17.5",
38
38
  "shellcheck-py>=0.11.0.1",
39
- "ty>=0.0.86",
40
- "types-pyyaml>=6.0.12.20260906",
41
- "typos>=1.51.1",
39
+ "ty>=0.0.104",
40
+ "types-pyyaml>=6.0.12.20261113",
41
+ "typos>=1.52.2",
42
42
  "yamllint>=1.38.0",
43
43
  ]
44
44
 
@@ -1,41 +1,41 @@
1
1
  [project]
2
2
  authors = [{ name = "Nathaniel Landau", email = "github@natelandau.com" }]
3
3
  dependencies = [
4
- "fastembed>=0.9.0",
4
+ "fastembed>=0.9.1",
5
5
  "nclutils>=4.0.0",
6
6
  "pyyaml>=6.0.3",
7
7
  "sqlite-vec>=0.1.9",
8
8
  "tomli-w>=1.2.0",
9
- "typer>=0.27.3",
9
+ "typer>=0.29.1",
10
10
  ]
11
11
  description = "Durable memory for coding agents, one folder of searchable pages per project."
12
12
  name = "sessionmemory"
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.13,<3.15"
15
- version = "0.18.0"
15
+ version = "0.19.0"
16
16
 
17
17
  [project.scripts]
18
18
  sessionmemory = "sessionmemory.entry:main"
19
19
 
20
20
  [dependency-groups]
21
21
  dev = [
22
- "commitizen>=4.19.2",
23
- "coverage>=7.16.2",
22
+ "commitizen>=4.19.3",
23
+ "coverage>=7.17.3",
24
24
  "duty>=1.10.1",
25
- "gate-cache>=0.6.0",
26
- "prek>=0.5.5",
25
+ "gate-cache>=0.7.0",
26
+ "prek>=0.5.11",
27
27
  "pytest-clarity>=1.0.1",
28
28
  "pytest-cov>=7.1.0",
29
29
  "pytest-devtools>=1.3.0",
30
- "pytest-mock>=3.16.0",
30
+ "pytest-mock>=3.17.0",
31
31
  "pytest-xdist>=3.8.0",
32
- "pytest>=9.1.1",
32
+ "pytest>=9.2.0",
33
33
  "rich>=15.0.0",
34
- "ruff>=0.17.0",
34
+ "ruff>=0.17.5",
35
35
  "shellcheck-py>=0.11.0.1",
36
- "ty>=0.0.86",
37
- "types-pyyaml>=6.0.12.20260906",
38
- "typos>=1.51.1",
36
+ "ty>=0.0.104",
37
+ "types-pyyaml>=6.0.12.20261113",
38
+ "typos>=1.52.2",
39
39
  "yamllint>=1.38.0",
40
40
  ]
41
41
 
@@ -55,6 +55,11 @@ SUPERSEDES = typer.Option(
55
55
  None, "--supersedes", help="The spec this one replaces, by name; it is marked superseded."
56
56
  )
57
57
  TOPIC = typer.Option(None, "--topic", help="A topic tag, without the leading hash.")
58
+ DETAIL = typer.Option(
59
+ None,
60
+ "--detail",
61
+ help="Context written as nested bullets under the item: why, where, what was tried.",
62
+ )
58
63
 
59
64
 
60
65
  def _report(path: Path, title: str, *, as_json: bool, uuid: str | None = None) -> None:
@@ -200,33 +205,13 @@ def new_reference(
200
205
  _new_living_document(paths.reference_dir, title, body, body_file, cwd, as_json=as_json)
201
206
 
202
207
 
203
- def _warn_about_shape(*, in_use: list[str], title: str, topic: str | None) -> None:
204
- """Warn, without blocking the write, about a new topic tag or an overlong description.
205
-
206
- `in_use` is read before the write, since the line just written always carries its own
207
- topic.
208
- """
209
- if topic is not None:
210
- tag = topic.strip().removeprefix("#")
211
- if tag and in_use and tag not in in_use:
212
- pp.warning(
213
- f"#{tag} is a new topic in this backlog",
214
- details=[f"in use: {', '.join(in_use)}"],
215
- )
216
- length = len(title.strip())
217
- if length > backlog.LONG_DESCRIPTION:
218
- pp.warning(
219
- f"the description is {length} characters, over the {backlog.LONG_DESCRIPTION} limit",
220
- details=["keep a line to one sentence and put detail in a spec"],
221
- )
222
-
223
-
224
208
  @app.command("backlog", help="Add one open item to this project's backlog.md.")
225
209
  def new_backlog(
226
210
  kind: Kind = KIND,
227
211
  size: Size = SIZE,
228
212
  title: str = DESCRIPTION,
229
213
  topic: str | None = TOPIC,
214
+ detail: str | None = DETAIL,
230
215
  cwd: Path | None = CWD_OPTION,
231
216
  *,
232
217
  as_json: bool = JSON_OPTION,
@@ -241,13 +226,22 @@ def new_backlog(
241
226
  path = paths.backlog_path(vault, slug)
242
227
  in_use = backlog.topics(path)
243
228
  try:
244
- line = backlog.add_item(
245
- path, kind=kind.value, size=size.value, description=title, topic=topic, today=today()
229
+ block = backlog.add_item(
230
+ path,
231
+ kind=kind.value,
232
+ size=size.value,
233
+ description=title,
234
+ topic=topic,
235
+ today=today(),
236
+ detail=detail,
246
237
  )
247
238
  except backlog.BacklogError as error:
248
239
  fail(str(error))
249
- _warn_about_shape(in_use=in_use, title=title, topic=topic)
240
+ for warning in backlog.shape_warnings(
241
+ in_use=in_use, description=title, topic=topic, detail=detail
242
+ ):
243
+ pp.warning(warning.message, details=[warning.advice])
250
244
  if as_json:
251
- emit_json({"path": str(path), "line": line})
245
+ emit_json({"path": str(path), "line": block[0], "detail": block[1:]})
252
246
  return
253
- emit_value(f"{line}\n{path}")
247
+ emit_value("\n".join([*block, str(path)]))
@@ -6,11 +6,17 @@ does not depend on that shape: a person writes lines by hand, often as plain pro
6
6
  every top-level bullet with text is an item. The line has no checkbox: finished work is
7
7
  deleted, and git history is the record of it, so there is nothing to tick. Deleting a
8
8
  line needs no validation and stays a direct edit.
9
+
10
+ Context that would crowd the line goes in an optional detail block: indented bullets
11
+ directly under it. Counting ignores indented lines, so the headline stays the item and
12
+ the detail never inflates the count.
9
13
  """
10
14
 
11
15
  from __future__ import annotations
12
16
 
13
17
  import re
18
+ import textwrap
19
+ from dataclasses import dataclass
14
20
  from typing import TYPE_CHECKING
15
21
 
16
22
  from sessionmemory.lib import atomic
@@ -22,14 +28,32 @@ KINDS = ("feat", "fix", "refactor", "perf", "docs", "test", "build", "ci", "deci
22
28
  SIZES = ("S", "M", "L")
23
29
  HEADING = "# Backlog"
24
30
  _SECTION_PREFIX = "## "
25
- LONG_DESCRIPTION = 200
31
+ LONG_DESCRIPTION = 120
32
+ LONG_DETAIL = 1500
33
+ DETAIL_BULLET = " - "
34
+ _DETAIL_CONTINUATION = " "
35
+ DETAIL_WIDTH = 88
36
+ _TICKED = ("- [x]", "- [X]")
26
37
  _TOPIC_TAG = re.compile(r"\[#([^\s\]]+)\]")
38
+ _BULLET_MARKER = re.compile(r"^-(\s+|$)")
27
39
 
28
40
 
29
41
  class BacklogError(ValueError):
30
42
  """An item field that cannot be written as a well-formed line."""
31
43
 
32
44
 
45
+ @dataclass(frozen=True)
46
+ class ShapeWarning:
47
+ """A field that is written as given but likely misplaced, with what to do instead."""
48
+
49
+ message: str
50
+ advice: str
51
+
52
+
53
+ def _tag(topic: str) -> str:
54
+ return topic.strip().removeprefix("#")
55
+
56
+
33
57
  def format_item(*, kind: str, size: str, description: str, topic: str | None, today: str) -> str:
34
58
  """Return the checklist line for one open item, validating every field.
35
59
 
@@ -64,7 +88,7 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
64
88
  line = f"- [{size}] {description} - {today}"
65
89
  if topic is None:
66
90
  return line
67
- topic = topic.strip().removeprefix("#")
91
+ topic = _tag(topic)
68
92
  if not topic:
69
93
  msg = "the topic is empty"
70
94
  raise BacklogError(msg)
@@ -77,6 +101,91 @@ def format_item(*, kind: str, size: str, description: str, topic: str | None, to
77
101
  return f"{line} [#{topic}]"
78
102
 
79
103
 
104
+ def format_detail(detail: str | None) -> list[str]:
105
+ """Return the nested bullets that carry an item's detail under its headline.
106
+
107
+ Each line of `detail` becomes one bullet, so a markdown viewer shows the lines apart
108
+ instead of joining them into the item's paragraph. A bullet the caller wrote keeps
109
+ its text without gaining a second marker. Blank lines are dropped so the item stays
110
+ one tight block and the next item's insert point is unambiguous.
111
+
112
+ Args:
113
+ detail (str | None): Free text, possibly several lines, or None for no detail.
114
+
115
+ Returns:
116
+ list[str]: The lines to write, each bullet starting with `DETAIL_BULLET` and
117
+ wrapped onto indented continuation lines, or an empty list when there is no
118
+ detail.
119
+ """
120
+ texts = (_BULLET_MARKER.sub("", line.strip()) for line in (detail or "").splitlines())
121
+ return [
122
+ wrapped
123
+ for text in texts
124
+ if text
125
+ for wrapped in textwrap.wrap(
126
+ text,
127
+ width=DETAIL_WIDTH,
128
+ initial_indent=DETAIL_BULLET,
129
+ subsequent_indent=_DETAIL_CONTINUATION,
130
+ break_long_words=False,
131
+ break_on_hyphens=False,
132
+ )
133
+ ]
134
+
135
+
136
+ def shape_warnings(
137
+ *, in_use: list[str], description: str, topic: str | None, detail: str | None
138
+ ) -> list[ShapeWarning]:
139
+ """Return what is likely misplaced in an item that is otherwise well-formed.
140
+
141
+ None of these refuses the write: a new topic may be deliberate, and length is advice.
142
+
143
+ Args:
144
+ in_use (list[str]): The topics on the backlog before this item, from `topics`.
145
+ description (str): The item's description as given.
146
+ topic (str | None): The item's topic as given, or None.
147
+ detail (str | None): The item's detail as given, or None.
148
+
149
+ Returns:
150
+ list[ShapeWarning]: One per problem, empty when the item is well placed.
151
+ """
152
+ warnings: list[ShapeWarning] = []
153
+ tag = _tag(topic) if topic is not None else ""
154
+ if tag and in_use and tag not in in_use:
155
+ warnings.append(
156
+ ShapeWarning(f"#{tag} is a new topic in this backlog", f"in use: {', '.join(in_use)}")
157
+ )
158
+ length = len(description.strip())
159
+ if length > LONG_DESCRIPTION:
160
+ warnings.append(
161
+ ShapeWarning(
162
+ f"the description is {length} characters, longer than {LONG_DESCRIPTION}",
163
+ "keep the line to one short sentence and move context into --detail",
164
+ )
165
+ )
166
+ detail_length = len((detail or "").strip())
167
+ if detail_length > LONG_DETAIL:
168
+ warnings.append(
169
+ ShapeWarning(
170
+ f"the detail is {detail_length} characters, longer than {LONG_DETAIL}",
171
+ "a design this size belongs in a spec",
172
+ )
173
+ )
174
+ return warnings
175
+
176
+
177
+ def is_ticked(line: str) -> bool:
178
+ """Return whether `line` is a ticked top-level bullet: finished work left in place.
179
+
180
+ Args:
181
+ line (str): One line of `backlog.md`.
182
+
183
+ Returns:
184
+ bool: True for a `- [x]` or `- [X]` line at column 0.
185
+ """
186
+ return line.startswith(_TICKED)
187
+
188
+
80
189
  def is_item(line: str) -> bool:
81
190
  """Return whether `line` is an open item, the only lines the session start counts.
82
191
 
@@ -88,7 +197,7 @@ def is_item(line: str) -> bool:
88
197
  whatever size, date, or topic it carries. False for a ticked `- [x]` line,
89
198
  an indented sub-bullet, an empty bullet, and anything that is not a bullet.
90
199
  """
91
- if not line.startswith("- ") or line.startswith(("- [x]", "- [X]")):
200
+ if not line.startswith("- ") or is_ticked(line):
92
201
  return False
93
202
  return bool(line.removeprefix("- ").removeprefix("[ ]").strip())
94
203
 
@@ -108,12 +217,12 @@ def topics(path: Path) -> list[str]:
108
217
  return sorted({tag for line in lines if is_item(line) for tag in _TOPIC_TAG.findall(line)})
109
218
 
110
219
 
111
- def _insert(lines: list[str], kind: str, item: str) -> list[str]:
112
- """Place `item` at the end of the `## kind` section, or open that section last."""
220
+ def _insert(lines: list[str], kind: str, block: list[str]) -> list[str]:
221
+ """Place `block` at the end of the `## kind` section, or open that section last."""
113
222
  heading = f"{_SECTION_PREFIX}{kind}"
114
223
  start = next((i for i, line in enumerate(lines) if line.rstrip() == heading), None)
115
224
  if start is None:
116
- return [*lines, "", heading, "", item]
225
+ return [*lines, "", heading, "", *block]
117
226
  end = next(
118
227
  (i for i in range(start + 1, len(lines)) if lines[i].startswith(_SECTION_PREFIX)),
119
228
  len(lines),
@@ -122,14 +231,21 @@ def _insert(lines: list[str], kind: str, item: str) -> list[str]:
122
231
  while last > start + 1 and not lines[last - 1].strip():
123
232
  last -= 1
124
233
  if last == start + 1:
125
- return [*lines[:last], "", item, *lines[last:]]
126
- return [*lines[:last], item, *lines[last:]]
234
+ return [*lines[:last], "", *block, *lines[last:]]
235
+ return [*lines[:last], *block, *lines[last:]]
127
236
 
128
237
 
129
238
  def add_item(
130
- path: Path, *, kind: str, size: str, description: str, topic: str | None, today: str
131
- ) -> str:
132
- """Append one open item under its kind heading and return the line written.
239
+ path: Path,
240
+ *,
241
+ kind: str,
242
+ size: str,
243
+ description: str,
244
+ topic: str | None,
245
+ today: str,
246
+ detail: str | None = None,
247
+ ) -> list[str]:
248
+ """Append one open item under its kind heading and return the lines written.
133
249
 
134
250
  A missing file starts with `# Backlog`. An existing file keeps whatever heads it,
135
251
  since the `# Backlog` heading is never inserted into a file someone else structured.
@@ -141,14 +257,18 @@ def add_item(
141
257
  description (str): The imperative description.
142
258
  topic (str | None): The tag, or None for none.
143
259
  today (str): The date as `YYYY-MM-DD`.
260
+ detail (str | None): Context written as indented lines under the item, or None.
144
261
 
145
262
  Returns:
146
- str: The line written, without a trailing newline.
263
+ list[str]: The item line followed by its detail lines, without newlines.
147
264
 
148
265
  Raises:
149
266
  BacklogError: A field cannot be written as a well-formed line.
150
267
  """
151
- item = format_item(kind=kind, size=size, description=description, topic=topic, today=today)
268
+ block = [
269
+ format_item(kind=kind, size=size, description=description, topic=topic, today=today),
270
+ *format_detail(detail),
271
+ ]
152
272
  lines = path.read_text(encoding="utf-8").rstrip().splitlines() if path.is_file() else [HEADING]
153
- atomic.write_text(path, "\n".join(_insert(lines, kind=kind, item=item)) + "\n")
154
- return item
273
+ atomic.write_text(path, "\n".join(_insert(lines, kind=kind, block=block)) + "\n")
274
+ return block
@@ -74,8 +74,9 @@ One folder per project under `projects/`. Inside each:
74
74
  indexed. `plans/` is scratch and is never committed: `.gitignore` and the plugin's
75
75
  commits both leave it out.
76
76
  - `backlog.md` is the list of open items for the project: every top-level bullet is an
77
- open item, under any heading or none. A question for the user goes under `## decide`.
78
- A finished item is deleted, not ticked.
77
+ open item, under any heading or none, and the indented lines under it are its detail.
78
+ A question for the user goes under `## decide`. A finished item is deleted with its
79
+ detail, not ticked.
79
80
 
80
81
  The `{MODEL_CODE}.sqlite3` file inside a field is its vector index. It is
81
82
  derived from the pages beside it, gitignored, and rebuilt by `sessionmemory reindex`.
@@ -16,6 +16,7 @@ from pathlib import Path
16
16
  from typing import TYPE_CHECKING
17
17
 
18
18
  from sessionmemory.lib import (
19
+ backlog,
19
20
  changes,
20
21
  commits,
21
22
  field,
@@ -147,9 +148,6 @@ def dead_projects(vault: Path, _embedder: Embedder) -> list[Finding]:
147
148
  ]
148
149
 
149
150
 
150
- _TICKED = ("- [x]", "- [X]")
151
-
152
-
153
151
  def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
154
152
  """Report a ticked top-level bullet in a backlog.
155
153
 
@@ -162,7 +160,7 @@ def ticked_backlog_lines(vault: Path, _embedder: Embedder) -> list[Finding]:
162
160
  if not path.is_file():
163
161
  continue
164
162
  for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
165
- if line.startswith(_TICKED):
163
+ if backlog.is_ticked(line):
166
164
  message = f"line {number}: ticked; finished work is deleted, not ticked"
167
165
  findings.append(Finding("backlog", str(path), message))
168
166
  return findings
@@ -145,15 +145,17 @@ all for a script.
145
145
  - Past sessions, one page each: `{command} search "<words>" --logs`. Search them
146
146
  for why something was decided, what happened the last time an area changed, or
147
147
  whether a fix was already tried.
148
- - Open work: read `backlog.md`. Any top-level bullet is an open item. Under a
148
+ - Open work: read `backlog.md`. Any top-level bullet is an open item, and the
149
+ indented lines under it are its detail. Under a
149
150
  `## <kind>` heading (feat, fix, refactor, perf, docs, test, build, ci, decide), the
150
151
  full shape is sized S, M, or L: `- [S] <imperative description> - <YYYY-MM-DD> [#topic]`.
151
152
  Add one with
152
153
  `{command} new backlog --kind <kind> --size <S|M|L> --title "..." --topic <topic> --cwd .`,
153
- which writes that shape and creates the file or heading when missing. Questions
154
- for the user to answer go under `## decide`. Delete a finished line, and one
155
- that will never be done, directly; never tick or annotate it. Git history is the
156
- record of what was finished.
154
+ which writes that shape and creates the file or heading when missing. Keep the
155
+ title to one short sentence and pass context (why, where, what was tried) with
156
+ `--detail "..."`, in single quotes when it holds a backtick or `$`. Questions for
157
+ the user to answer go under `## decide`. Delete a finished item with its detail,
158
+ and one that will never be done, directly; never tick or annotate it. Git history is the record of what was finished.
157
159
  - Specs: `specs/` holds one design record per feature, named `<date>-<topic>.md`
158
160
  and kept after the work ships. Before designing or changing a feature, search
159
161
  them: `{command} search "<words>" --specs` (listing the directory works too), so a