sessionmemory 0.17.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.17.0 → sessionmemory-0.19.0}/PKG-INFO +10 -8
  2. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/README.md +7 -5
  3. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/pyproject.toml +13 -13
  4. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/pyproject.toml.orig +13 -13
  5. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/local.py +13 -5
  6. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/new.py +20 -26
  7. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/backlog.py +135 -15
  8. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/bootstrap.py +3 -2
  9. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/doctor.py +13 -12
  10. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/gitinfo.py +2 -2
  11. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/inject.py +7 -5
  12. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmd.py +225 -55
  13. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registry.py +23 -0
  14. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/resolve.py +9 -2
  15. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/__init__.py +0 -0
  16. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/cli.py +0 -0
  17. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/__init__.py +0 -0
  18. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/_common.py +0 -0
  19. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/delete.py +0 -0
  20. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/doctor.py +0 -0
  21. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/export.py +0 -0
  22. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/init.py +0 -0
  23. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/inject.py +0 -0
  24. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/log.py +0 -0
  25. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/path.py +0 -0
  26. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/project.py +0 -0
  27. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reconcile.py +0 -0
  28. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/reindex.py +0 -0
  29. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/commands/search.py +0 -0
  30. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/entry.py +0 -0
  31. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/__init__.py +0 -0
  32. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/atomic.py +0 -0
  33. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/changes.py +0 -0
  34. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/commits.py +0 -0
  35. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/config.py +0 -0
  36. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/embed.py +0 -0
  37. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/export.py +0 -0
  38. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/field.py +0 -0
  39. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/fieldindex.py +0 -0
  40. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/frontmatter.py +0 -0
  41. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/ids.py +0 -0
  42. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localdeclined.py +0 -0
  43. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localmanifest.py +0 -0
  44. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/localtree.py +0 -0
  45. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/log.py +0 -0
  46. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/paths.py +0 -0
  47. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/reconcile.py +0 -0
  48. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/registration.py +0 -0
  49. {sessionmemory-0.17.0 → sessionmemory-0.19.0}/src/sessionmemory/lib/settingsdiff.py +0 -0
  50. {sessionmemory-0.17.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.17.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.17.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.17.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
 
@@ -69,12 +69,18 @@ def _checkout(cwd: Path | None) -> localmd.Checkout:
69
69
  """
70
70
  vault = require_vault()
71
71
  slug, resolved = require_registered(vault=vault, cwd=cwd)
72
+ project = resolved.project
73
+ # Only a match by path, which resolution allows only outside any repository, may root
74
+ # the checkout at the registered folder.
75
+ by_path = resolved.matched_by == "path" and project is not None and project.root
76
+ registered_root = Path(project.root) if by_path else None
72
77
  try:
73
78
  return localmd.checkout(
74
79
  vault=vault,
75
80
  slug=slug,
76
81
  cwd=_common.target_dir(cwd),
77
82
  worktree=resolved.worktree_root,
83
+ registered_root=registered_root,
78
84
  )
79
85
  except localmd.LocalMdError as err:
80
86
  fail(err.message, details=err.details)
@@ -86,14 +92,14 @@ def _or_fail(co: localmd.Checkout, doing: str) -> Generator[None]:
86
92
 
87
93
  Args:
88
94
  co (localmd.Checkout): The checkout being worked on.
89
- doing (str): What failed, as in "could not <doing> the entries of <worktree>".
95
+ doing (str): What failed, as in "could not <doing> the entries of <root>".
90
96
  """
91
97
  try:
92
98
  yield
93
99
  except localmd.LocalMdError as err:
94
100
  fail(err.message, details=err.details)
95
101
  except OSError as err:
96
- fail(f"could not {doing} the entries of {co.worktree}: {err}")
102
+ fail(f"could not {doing} the entries of {co.root}: {err}")
97
103
 
98
104
 
99
105
  def _migrate(co: localmd.Checkout) -> None:
@@ -161,7 +167,7 @@ def _waiting(co: localmd.Checkout, tracked: set[str]) -> tuple[list[localmd.Entr
161
167
  except localmd.LocalMdError as err:
162
168
  pp.error(err.message, details=err.details)
163
169
  except OSError as err:
164
- pp.error(f"could not read the entries of {co.worktree}: {err}")
170
+ pp.error(f"could not read the entries of {co.root}: {err}")
165
171
  return [], False
166
172
 
167
173
 
@@ -808,7 +814,7 @@ def _declinable(co: localmd.Checkout, raw: str, cwd: Path, present: list[str]) -
808
814
  except localmd.LocalMdError as err:
809
815
  pp.error(err.message, details=err.details)
810
816
  except OSError as err:
811
- pp.error(f"could not read {raw} in {co.worktree}: {err}")
817
+ pp.error(f"could not read {raw} in {co.root}: {err}")
812
818
  return None
813
819
 
814
820
 
@@ -904,7 +910,9 @@ def status_command(cwd: Path | None = CWD_OPTION, as_json: bool = JSON_OPTION) -
904
910
  asked = {item.name for item in askable}
905
911
 
906
912
  def is_ignored(item: localmd.Entry) -> bool | None:
907
- return item.name in ignored if item.name in asked else None
913
+ if ignored is None or item.name not in asked:
914
+ return None
915
+ return item.name in ignored
908
916
 
909
917
  rows = [
910
918
  _status_row(
@@ -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,
@@ -36,7 +37,7 @@ from sessionmemory.lib.frontmatter import (
36
37
  )
37
38
 
38
39
  if TYPE_CHECKING:
39
- from collections.abc import Callable
40
+ from collections.abc import Callable, Mapping
40
41
 
41
42
  from sessionmemory.lib.embed import Embedder
42
43
 
@@ -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
@@ -516,16 +514,20 @@ def _declined_findings(co: localmd.Checkout, *, checked: bool) -> list[Finding]:
516
514
  return findings
517
515
 
518
516
 
519
- def _project_local_findings(vault: Path, slug: str, root: Path | None) -> list[Finding]:
517
+ def _project_local_findings(
518
+ vault: Path, slug: str, root: Path | None, projects: Mapping[str, registry.Project]
519
+ ) -> list[Finding]:
520
520
  """Report one project's local entries, checking the checkout only when `root` exists."""
521
521
  findings = []
522
522
  legacy = _legacy_finding(vault, slug)
523
523
  if legacy is not None:
524
524
  findings.append(legacy)
525
- # With no registered root nothing below reaches git, so the vault is a harmless stand-in.
526
- co = localmd.Checkout(
527
- worktree=root or vault, vault=vault, slug=slug, local=paths.local_dir(vault, slug)
528
- )
525
+ if root is not None and root.is_dir():
526
+ checked = True
527
+ co = localmd.checkout_at(vault=vault, slug=slug, root=root, projects=projects)
528
+ else:
529
+ checked = False
530
+ co = localmd.vault_stand_in(vault=vault, slug=slug)
529
531
  findings.extend(_manifest_findings(co))
530
532
  try:
531
533
  items = localmd.vault_entries(co)
@@ -544,7 +546,6 @@ def _project_local_findings(vault: Path, slug: str, root: Path | None) -> list[F
544
546
  for item in items:
545
547
  findings.extend(_import_findings(item))
546
548
  findings.extend(_repository_findings(item))
547
- checked = root is not None and root.is_dir()
548
549
  findings.extend(_declined_findings(co, checked=checked))
549
550
  if not checked:
550
551
  return findings
@@ -588,7 +589,7 @@ def local_instructions(vault: Path, _embedder: Embedder) -> list[Finding]:
588
589
  for slug in paths.iter_project_slugs(vault):
589
590
  project = projects.get(slug)
590
591
  root = Path(project.root) if project and project.root else None
591
- findings.extend(_project_local_findings(vault, slug, root))
592
+ findings.extend(_project_local_findings(vault, slug, root, projects))
592
593
  return findings
593
594
 
594
595
 
@@ -31,7 +31,7 @@ GIT_TIMEOUT_SECONDS = 10
31
31
 
32
32
  # The one git failure that is an answer rather than an outage. Every other non-zero exit,
33
33
  # such as a `safe.directory` refusal or a held index lock, leaves the question open.
34
- _NOT_A_REPOSITORY = "not a git repository"
34
+ NOT_A_REPOSITORY = "not a git repository"
35
35
 
36
36
 
37
37
  @dataclass(frozen=True)
@@ -118,7 +118,7 @@ def _git(cwd: Path, *args: str) -> _GitAnswer:
118
118
  if completed is None:
119
119
  return _GitAnswer(stdout=None, answered=False)
120
120
  if completed.returncode != 0:
121
- return _GitAnswer(stdout=None, answered=_NOT_A_REPOSITORY in completed.stderr.lower())
121
+ return _GitAnswer(stdout=None, answered=NOT_A_REPOSITORY in completed.stderr.lower())
122
122
  return _GitAnswer(stdout=completed.stdout.strip() or None, answered=True)
123
123
 
124
124