reqdeck 0.1.0__tar.gz → 0.2.0__tar.gz

reqdeck-0.2.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+What changed in each release of reqdeck. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+Every change a user would notice gets a line under **Unreleased**, in the commit that makes
+it. To release: rename **Unreleased** to the version and date, open a new empty
+**Unreleased** above it, bump the version in `reqdeck/__init__.py` and
+`.claude-plugin/plugin.json`, re-record the README's media with `scripts/record-demo.sh`,
+then tag `vX.Y.Z` — and paste the section into the GitHub release.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-17
+
+### Added
+
+- The TUI reloads from disk every 30 seconds, so what an agent or an editor writes shows up
+  on its own. `Reloading` spins at the left of the hint line while it runs; a reload that
+  finds nothing changed redraws nothing, and one that does keeps the reading pane where it
+  was scrolled. `"reload"` in `~/.config/reqdeck/tui.json` sets the seconds, `0` turns it off.
+- Every requirement shows how far it is built, beside its review status: Done, Untested,
+  Partial, Not implemented or Unsatisfied, judged over it and everything that satisfies it, so
+  a user story is Done only once its whole chain is. The tree marks it `✓` `◑` `◔` `○` `✗`, the
+  card's title carries it, the level view counts the Done per unit, and `reqdeck get` prints
+  it with what keeps it from Done — `progress` in `--json`.
+- `satisfied`, `code` and `test` on a `[[levels]]` entry set what that level needs before it is
+  done. Unset, they follow from `satisfies`, the unit's `code` and the verification method, as
+  before. `code = true` or `test = true` on a `traced = false` level is now allowed, met by
+  markers on every requirement beneath it.
+
+### Changed
+
+- A requirement that must both be satisfied from below and named by code is done either way:
+  broken down, with code naming every requirement beneath it, or implemented as it stands,
+  with code naming it. Before, it needed its own code marker and something satisfying it — an
+  interface requirement with code but nothing satisfying it was a gap, and so was one whose
+  code sat on the software requirements beneath it.
+- A test beneath a requirement counts for it only where its level must be satisfied, and then
+  every requirement beneath it needs one — as for code. Before, one test anywhere beneath was
+  enough, so a system requirement with one tested and one untested software requirement
+  beneath it counted as tested.
+- `r` reloads in the background with the same spinner, instead of freezing the TUI while it
+  reads. A file that fails to load is reported once, not on every reload.
+
+## [0.1.0] - 2026-10-10
+
+First release: CSV requirements and open questions in your repository, `@REQ_REF` markers
+in code and tests, the `reqdeck` CLI and TUI, and the skills for Claude Code.
+
+[Unreleased]: https://github.com/danielriege/reqdeck/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/danielriege/reqdeck/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/danielriege/reqdeck/releases/tag/v0.1.0

{reqdeck-0.1.0 → reqdeck-0.2.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: reqdeck
-Version: 0.1.0
+Version: 0.2.0
 Summary: Requirements, open questions and traceability in your git repo — a CLI, a TUI, and skills for your AI agent
 Project-URL: Homepage, https://github.com/danielriege/reqdeck
 Project-URL: Source, https://github.com/danielriege/reqdeck
 Project-URL: Issues, https://github.com/danielriege/reqdeck/issues
-Project-URL: Changelog, https://github.com/danielriege/reqdeck/releases
+Project-URL: Changelog, https://github.com/danielriege/reqdeck/blob/main/CHANGELOG.md
 Author: Daniel Riege
 License-Expression: MIT
 License-File: LICENSE
@@ -32,7 +32,7 @@ Description-Content-Type: text/markdown
 Think of <a href="https://www.ibm.com/products/requirements-management">IBM DOORS</a>, but it lives in your git repo, fits in your terminal, and your AI agent can read it.
 <br><br>
 
-<a href="https://github.com/danielriege/reqdeck/actions/workflows/ci.yml"><img src="https://github.com/danielriege/reqdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://github.com/danielriege/reqdeck/actions/workflows/release.yml"><img src="https://github.com/danielriege/reqdeck/actions/workflows/release.yml/badge.svg" alt="Release"></a>
 <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
 <a href="https://pypi.org/project/reqdeck/"><img src="https://img.shields.io/pypi/v/reqdeck" alt="PyPI"></a>
 <a href="https://github.com/danielriege/reqdeck/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
@@ -158,6 +158,11 @@ verification method fits, where a marker goes.
 status, statement, detail tables and fields — beside the open questions by topic. The tree
 always has the cursor; the right pane shows what it highlights.
 
+Beside each requirement in the tree are two marks. The letter is its review status: `A`ccepted,
+`P`roposed, `R`eopened. The symbol is how far it is built, judged over it and everything that
+satisfies it: `✓` done, `◑` untested, `◔` partial, `○` not implemented, `✗` unsatisfied. The
+card says which requirements beneath it keep it from done, and `reqdeck get` prints the same.
+
 | | |
 |---|---|
 | `j` `k` `h` `l` · `gg` `G` | Move through the tree, as in vim |
@@ -183,6 +188,11 @@ Flexoki), each given a full colour suite by a file in [reqdeck/themes/](https://
 where you can add your own. Your theme and sidebar width are remembered in
 `~/.config/reqdeck/tui.json`.
 
+It reloads from disk every 30 seconds, so what an agent or your editor writes shows up on its
+own — `Reloading` spins at the left of the hint line while it does, and only a change redraws
+anything. `r` reloads at once. Set `"reload"` in `tui.json` to the seconds between reloads, or
+`0` to turn it off.
+
 ## The CLI
 
 ```bash
@@ -264,6 +274,7 @@ traced = false
 kind = "SW"
 satisfies = ["SYS"]
 topic = true
+code = true                   # what it needs before it is done — see below
 
 [verification.T]
 name = "Test"
@@ -282,6 +293,51 @@ command = "nvim +{line} {file}"           # or "code --goto {file}:{line}"
 Without `[verification]` the methods are A, I, D and T. Without `[markers]` every common
 source file is scanned and a marker may sit anywhere.
 
+### What a level needs
+
+Three keys on a `[[levels]]` entry say what each of its requirements needs before it is done.
+Each is `true` or `false`; left out, it takes the default in the last column, which is how
+reqdeck behaved before the keys existed.
+
+| Key | Met when | Left out |
+|---|---|---|
+| `satisfied` | a requirement of a lower level names it in `satisfies` — **or**, where the level also has `code = true`, a code marker names it itself | `true` if another level lists this one in its `satisfies` |
+| `code` | a code `@REQ_REF` names it — **or**, where the level also has `satisfied = true`, **every** requirement beneath it is named by code, or is satisfied by requirements that all are | the unit's `code = true` |
+| `test` | a test `@REQ_REF` names it — **or**, where the level also has `satisfied = true`, **every** requirement beneath it is named by a test, or is satisfied by requirements that all are | the verification method's `automated = true` |
+
+`code` and `test` follow one rule: **a marker on the requirement itself, or a marker on every
+branch beneath it.** "Beneath" is everything that satisfies it, all the way down, and *every
+branch* means each requirement satisfying it is named by a marker, or is in turn satisfied by
+requirements that all are. One branch without is enough to leave it short. With three
+software requirements satisfying a system requirement and code on two, the system
+requirement is not coded and shows as partial; code on the third makes it coded. Tests are
+counted the same way, separately: code on all three and a test on two leaves it untested.
+
+So a level with `satisfied = true` and `code = true` is done in either of two ways:
+
+- **Broken down.** Lower requirements satisfy it, and code names every one of them (or every
+  one of theirs, where they are broken down further).
+- **Implemented as it stands.** Code names it directly, and nothing needs to satisfy it.
+
+`test = true` adds the same again for tests, on top of either way.
+
+With `satisfied = false`, only a marker on the requirement itself counts, for `code` and for
+`test`. A level with `traced = false` may never be named by a marker directly, so `code = true`
+or `test = true` there needs `satisfied = true` — the markers can only be beneath it — and
+`check` refuses the config otherwise.
+
+`coverage`, `trace`, `get` and the progress marks in the TUI all judge by these same rules.
+
+```toml
+[[levels]]
+kind = "TSR"                  # a technical system requirement
+satisfies = ["STORY"]
+traced = false                # never named by code itself...
+satisfied = true              # ...so a TSSR or an ICD must satisfy it,
+code = true                   # and code must name every one of those,
+test = true                   # and a test must name every one of those too
+```
+
 ## Limitations
 
 - **Small teams.** It is built for one person and their agents, or a handful of people. Two
@@ -300,6 +356,15 @@ source file is scanned and a marker may sit anywhere.
 python3 -m unittest discover tests     # the TUI tests skip without textual
 ```
 
+The demo GIF and the screenshot above are recorded, not drawn: `scripts/record-demo.sh`
+installs this checkout into a throwaway virtualenv and plays `docs/demo.tape` and
+`docs/document.tape` through [vhs](https://github.com/charmbracelet/vhs). It needs vhs and nvim.
+
+Every change a user would notice gets a line under `Unreleased` in
+[CHANGELOG.md](https://github.com/danielriege/reqdeck/blob/main/CHANGELOG.md), in the same
+commit. A release renames that section to its version; publishing refuses a version the
+changelog does not name.
+
 ## License
 
 MIT. See [LICENSE](https://github.com/danielriege/reqdeck/blob/main/LICENSE).

{reqdeck-0.1.0 → reqdeck-0.2.0}/README.md

@@ -5,7 +5,7 @@
 Think of <a href="https://www.ibm.com/products/requirements-management">IBM DOORS</a>, but it lives in your git repo, fits in your terminal, and your AI agent can read it.
 <br><br>
 
-<a href="https://github.com/danielriege/reqdeck/actions/workflows/ci.yml"><img src="https://github.com/danielriege/reqdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+<a href="https://github.com/danielriege/reqdeck/actions/workflows/release.yml"><img src="https://github.com/danielriege/reqdeck/actions/workflows/release.yml/badge.svg" alt="Release"></a>
 <img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+">
 <a href="https://pypi.org/project/reqdeck/"><img src="https://img.shields.io/pypi/v/reqdeck" alt="PyPI"></a>
 <a href="https://github.com/danielriege/reqdeck/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT license"></a>
@@ -131,6 +131,11 @@ verification method fits, where a marker goes.
 status, statement, detail tables and fields — beside the open questions by topic. The tree
 always has the cursor; the right pane shows what it highlights.
 
+Beside each requirement in the tree are two marks. The letter is its review status: `A`ccepted,
+`P`roposed, `R`eopened. The symbol is how far it is built, judged over it and everything that
+satisfies it: `✓` done, `◑` untested, `◔` partial, `○` not implemented, `✗` unsatisfied. The
+card says which requirements beneath it keep it from done, and `reqdeck get` prints the same.
+
 | | |
 |---|---|
 | `j` `k` `h` `l` · `gg` `G` | Move through the tree, as in vim |
@@ -156,6 +161,11 @@ Flexoki), each given a full colour suite by a file in [reqdeck/themes/](https://
 where you can add your own. Your theme and sidebar width are remembered in
 `~/.config/reqdeck/tui.json`.
 
+It reloads from disk every 30 seconds, so what an agent or your editor writes shows up on its
+own — `Reloading` spins at the left of the hint line while it does, and only a change redraws
+anything. `r` reloads at once. Set `"reload"` in `tui.json` to the seconds between reloads, or
+`0` to turn it off.
+
 ## The CLI
 
 ```bash
@@ -237,6 +247,7 @@ traced = false
 kind = "SW"
 satisfies = ["SYS"]
 topic = true
+code = true                   # what it needs before it is done — see below
 
 [verification.T]
 name = "Test"
@@ -255,6 +266,51 @@ command = "nvim +{line} {file}"           # or "code --goto {file}:{line}"
 Without `[verification]` the methods are A, I, D and T. Without `[markers]` every common
 source file is scanned and a marker may sit anywhere.
 
+### What a level needs
+
+Three keys on a `[[levels]]` entry say what each of its requirements needs before it is done.
+Each is `true` or `false`; left out, it takes the default in the last column, which is how
+reqdeck behaved before the keys existed.
+
+| Key | Met when | Left out |
+|---|---|---|
+| `satisfied` | a requirement of a lower level names it in `satisfies` — **or**, where the level also has `code = true`, a code marker names it itself | `true` if another level lists this one in its `satisfies` |
+| `code` | a code `@REQ_REF` names it — **or**, where the level also has `satisfied = true`, **every** requirement beneath it is named by code, or is satisfied by requirements that all are | the unit's `code = true` |
+| `test` | a test `@REQ_REF` names it — **or**, where the level also has `satisfied = true`, **every** requirement beneath it is named by a test, or is satisfied by requirements that all are | the verification method's `automated = true` |
+
+`code` and `test` follow one rule: **a marker on the requirement itself, or a marker on every
+branch beneath it.** "Beneath" is everything that satisfies it, all the way down, and *every
+branch* means each requirement satisfying it is named by a marker, or is in turn satisfied by
+requirements that all are. One branch without is enough to leave it short. With three
+software requirements satisfying a system requirement and code on two, the system
+requirement is not coded and shows as partial; code on the third makes it coded. Tests are
+counted the same way, separately: code on all three and a test on two leaves it untested.
+
+So a level with `satisfied = true` and `code = true` is done in either of two ways:
+
+- **Broken down.** Lower requirements satisfy it, and code names every one of them (or every
+  one of theirs, where they are broken down further).
+- **Implemented as it stands.** Code names it directly, and nothing needs to satisfy it.
+
+`test = true` adds the same again for tests, on top of either way.
+
+With `satisfied = false`, only a marker on the requirement itself counts, for `code` and for
+`test`. A level with `traced = false` may never be named by a marker directly, so `code = true`
+or `test = true` there needs `satisfied = true` — the markers can only be beneath it — and
+`check` refuses the config otherwise.
+
+`coverage`, `trace`, `get` and the progress marks in the TUI all judge by these same rules.
+
+```toml
+[[levels]]
+kind = "TSR"                  # a technical system requirement
+satisfies = ["STORY"]
+traced = false                # never named by code itself...
+satisfied = true              # ...so a TSSR or an ICD must satisfy it,
+code = true                   # and code must name every one of those,
+test = true                   # and a test must name every one of those too
+```
+
 ## Limitations
 
 - **Small teams.** It is built for one person and their agents, or a handful of people. Two
@@ -273,6 +329,15 @@ source file is scanned and a marker may sit anywhere.
 python3 -m unittest discover tests     # the TUI tests skip without textual
 ```
 
+The demo GIF and the screenshot above are recorded, not drawn: `scripts/record-demo.sh`
+installs this checkout into a throwaway virtualenv and plays `docs/demo.tape` and
+`docs/document.tape` through [vhs](https://github.com/charmbracelet/vhs). It needs vhs and nvim.
+
+Every change a user would notice gets a line under `Unreleased` in
+[CHANGELOG.md](https://github.com/danielriege/reqdeck/blob/main/CHANGELOG.md), in the same
+commit. A release renames that section to its version; publishing refuses a version the
+changelog does not name.
+
 ## License
 
 MIT. See [LICENSE](https://github.com/danielriege/reqdeck/blob/main/LICENSE).

{reqdeck-0.1.0 → reqdeck-0.2.0}/pyproject.toml

@@ -32,7 +32,7 @@ classifiers = [
 Homepage = "https://github.com/danielriege/reqdeck"
 Source = "https://github.com/danielriege/reqdeck"
 Issues = "https://github.com/danielriege/reqdeck/issues"
-Changelog = "https://github.com/danielriege/reqdeck/releases"
+Changelog = "https://github.com/danielriege/reqdeck/blob/main/CHANGELOG.md"
 
 [project.scripts]
 reqdeck = "reqdeck.cli:main"
@@ -49,4 +49,4 @@ packages = ["reqdeck"]
 "skills" = "reqdeck/skills"
 
 [tool.hatch.build.targets.sdist]
-include = ["reqdeck", "skills", "tests", "examples", "README.md", "LICENSE", "pyproject.toml"]
+include = ["reqdeck", "skills", "tests", "examples", "README.md", "CHANGELOG.md", "LICENSE", "pyproject.toml"]

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/__init__.py

@@ -1,3 +1,3 @@
 """reqdeck — requirements, open questions and traceability for a git repository."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/cli.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from . import __version__, config, ops, render, store
 from .config import STATUS
 from .markers import Ref
-from .model import Model, Req, split
+from .model import PROGRESS, Model, Req, split
 
 BOLD, DIM, RED, RESET = "\033[1m", "\033[2m", "\033[31m", "\033[0m"
 
@@ -77,6 +77,7 @@ def cmd_get(m: Model, args) -> int:
             "code_refs": [asdict(x) for x in refs if not x.is_test],
             "test_refs": [asdict(x) for x in refs if x.is_test],
             "covering_test_refs": [asdict(x) for x in m.covering_refs(rid) if x.is_test],
+            "progress": asdict(m.progress(rid)),
         }, indent=2))
         return 0
 
@@ -97,6 +98,13 @@ def cmd_get(m: Model, args) -> int:
         print(f"  {_c('Verification:', DIM)} {r.verification} — {v.name if v else '?'}")
     if r.status:
         print(f"  {_c('Status:', DIM)} {r.status}")
+    progress = m.progress(rid)
+    if progress.state:
+        print(f"  {_c('Progress:', DIM)} {progress.state} — {PROGRESS[progress.state]}")
+        for label, ids in (("nothing satisfies", progress.unsatisfied), ("no code", progress.uncoded),
+                           ("no test", progress.untested)):
+            if ids:
+                print(f"    {_c(label + ':', DIM)} {', '.join(ids)}")
     if r.security:
         print(f"  {_c('Security relevant:', DIM)} {r.security}")
     for k, v in r.extra.items():
@@ -207,8 +215,8 @@ GAP_LABELS = [
     ("dangling", "Satisfies a requirement that does not exist", True),
     ("orphans", "No satisfies link — traces to nothing", False),
     ("unsatisfied", "Nothing satisfies it yet", False),
-    ("untested", "Verification is automated, but no test references it or its children", False),
-    ("uncoded", "Implemented in software, but no code reference", False),
+    ("untested", "Needs a test, but none names it — or, where it must be satisfied, all that is beneath it", False),
+    ("uncoded", "Needs code, but none names it — or, where it must be satisfied, all that is beneath it", False),
     ("not_accepted", "Not yet accepted — awaiting review by the user", False),
 ]
 
@@ -259,15 +267,16 @@ def cmd_trace(m: Model, args) -> int:
             problems.append(f"{rid}: is a {r.kind}, which no code references directly — "
                             f"name what satisfies it instead ({below})")
             continue
-        code = [x for x in m.refs_for(rid) if not x.is_test]
+        code = m.code_refs(r)
         test = [x for x in m.covering_refs(rid) if x.is_test]
-        needs_code = m.code_bearing(rid)
-        needs_test = m.automated(r)
-        if needs_code and not code:
-            problems.append(f"{rid}: no code reference — put @REQ_REF({rid}) on what implements it")
-        if needs_test and not test:
-            problems.append(f"{rid}: verification is {r.verification}, so a test must name it — "
-                            f"add @REQ_REF({rid}) to the test function")
+        satisfied, needs_code, needs_test = m.needs(r)
+        missing = m.missing(r)
+        if "code" in missing:
+            beneath = ", or on what implements every requirement beneath it" if satisfied else ""
+            problems.append(f"{rid}: no code reference — put @REQ_REF({rid}) on what implements it{beneath}")
+        if "test" in missing:
+            beneath = ", or test every requirement beneath it" if satisfied else ""
+            problems.append(f"{rid}: needs a test — add @REQ_REF({rid}) to the test function{beneath}")
         results.append({"id": rid, "verification": r.verification, "status": r.status,
                         "code_refs": [asdict(x) for x in code],
                         "test_refs": [asdict(x) for x in test],

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/config.py

@@ -54,6 +54,18 @@ class Level:
     traced: bool = True
     separator: str = "_"
     digits: int = 3
+    #: What a requirement of this level must have before it is done; see
+    #: `Model.missing`. Unset keeps the defaults: `satisfied` where another
+    #: level names this one in its `satisfies`, `code` where the unit says
+    #: `code = true`, `test` where the verification method is automated.
+    #: A lower level must satisfy it — or, with `code`, its own code marker.
+    satisfied: bool | None = None
+    #: A code marker must name it — or, with `satisfied`, every requirement
+    #: beneath it must be named by code, or be satisfied by ones that are.
+    code: bool | None = None
+    #: A test marker must name it — or, with `satisfied`, every requirement
+    #: beneath it must be named by a test, or be satisfied by ones that are.
+    test: bool | None = None
 
 
 @dataclass
@@ -150,6 +162,17 @@ def load(root: Path) -> Config:
         for k in lv.satisfies:
             if k not in kinds:
                 raise ConfigError(f"{path}: level {lv.kind} satisfies unknown level {k}")
+        for key in ("satisfied", "code", "test"):
+            if getattr(lv, key) not in (None, True, False):
+                raise ConfigError(f"{path}: level {lv.kind}: {key} is true or false")
+        below = any(lv.kind in other.satisfies for other in levels)
+        for key in ("code", "test"):
+            if getattr(lv, key) and not lv.traced and not (lv.satisfied if lv.satisfied is not None else below):
+                raise ConfigError(f"{path}: level {lv.kind}: {key} = true with traced = false can only be "
+                                  f"met by markers beneath it, so it needs satisfied = true")
+        if lv.satisfied and not below:
+            raise ConfigError(f"{path}: level {lv.kind}: satisfied = true, but no level "
+                              f"names {lv.kind} in its satisfies")
 
     verification = {}
     for code, (name, definition, automated) in DEFAULT_VERIFICATION.items():

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/init.py

@@ -112,7 +112,12 @@ def _config(shape: str, req_dir: str, questions: str, sys_: str, sub: str, icd:
             split_tests: bool, headers: bool) -> str:
     out = ["# reqdeck configuration — https://github.com/danielriege/reqdeck", "",
            f'requirements = "{req_dir}"', f'questions = "{questions}"', "",
-           "# Most abstract first. `satisfies` names the levels a requirement may point at.", "",
+           "# Most abstract first. `satisfies` names the levels a requirement may point at.",
+           "# `satisfied`, `code` and `test` (true or false) set what a level needs before it is",
+           "# done; unset, they follow from `satisfies`, the unit's `code` and the verification.",
+           "# `code` and `test` are met by a marker on the requirement itself, or, with `satisfied`,",
+           "# by markers on every requirement beneath it; with `code`, its own marker also counts",
+           "# for `satisfied`. See the README.", "",
            '[[levels]]\nkind = "STORY"\ntitle = "User story"\nreviewed = false\ntraced = false\n'
            'separator = "-"\ndigits = 2\n']
     if shape == "3":

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/model.py

@@ -8,6 +8,7 @@
     m.up("ICD_BUS_014")         # what it satisfies, transitively
     m.down("TSR_009")           # what satisfies it, transitively
     m.covering_refs("TSR_009")  # markers on it or on anything beneath it
+    m.progress("SYS_004")       # how far it and everything beneath it is built
 
 Only `satisfies` is ever written, pointing one level up. The reverse direction
 is derived here, so the two can never disagree.
@@ -24,6 +25,17 @@ from .config import STATUS, Config
 from .markers import Ref
 from .store import Unit
 
+#: How far a requirement is built, least first. Derived from the links and the
+#: markers, never stored: the review status says whether it is right, this
+#: says whether it is there.
+PROGRESS = {
+    "Unsatisfied": "a lower level exists to satisfy it, and nothing does",
+    "Not implemented": "code is expected, here or beneath it, and none names it",
+    "Partial": "some of what is beneath it is built, not all",
+    "Untested": "the code is there; a test its verification asks for is not",
+    "Done": "coded, and tested where its verification asks, and so is everything beneath it",
+}
+
 SPLIT = re.compile(r"[\s,;]+")
 NONE = {"", "—", "-"}
 
@@ -68,6 +80,17 @@ class Req:
         return asdict(self)
 
 
+@dataclass
+class Progress:
+    #: One of PROGRESS, or empty where nothing traceable is asked of it or
+    #: of anything beneath it.
+    state: str
+    #: Below, or the requirement itself: what keeps it from Done.
+    unsatisfied: list[str] = field(default_factory=list)
+    uncoded: list[str] = field(default_factory=list)
+    untested: list[str] = field(default_factory=list)
+
+
 class Model:
     def __init__(self, cfg: Config):
         self.cfg = cfg
@@ -79,6 +102,7 @@ class Model:
         #: Problems found while loading, reported by `check`.
         self.load_problems: list[str] = []
         self.satisfied_by: dict[str, list[str]] = {}
+        self._progress: dict[str, Progress] = {}
 
     # ---------------------------------------------------------------- loading
 
@@ -139,6 +163,7 @@ class Model:
                 r.detail = text
 
     def relink(self) -> None:
+        self._progress = {}
         self.satisfied_by = {k: [] for k in self.reqs}
         for r in self.reqs.values():
             for target in r.satisfies:
@@ -221,6 +246,95 @@ class Model:
         lv = self.cfg.level(r.kind)
         return lv.traced if lv else True
 
+    def needs(self, r: Req) -> tuple[bool, bool, bool]:
+        """Whether `r` must be satisfied from below, named by code, named by a test.
+        Its level says so, or else the defaults described on `config.Level`."""
+        lv = self.cfg.level(r.kind)
+        satisfied = lv.satisfied if lv and lv.satisfied is not None else r.kind in self.cfg.parent_kinds
+        if lv and lv.code is not None:
+            code = lv.code
+        else:
+            code = self.reviewed(r) and self.code_bearing(r.id)
+        test = lv.test if lv and lv.test is not None else self.reviewed(r) and self.automated(r)
+        return satisfied, code, test
+
+    def code_refs(self, r: Req) -> list[Ref]:
+        """The code markers that bear on `r`: its own, and where its level must be
+        satisfied, those beneath it. Whether they are enough is `coded`."""
+        refs = self.covering_refs(r.id) if self.needs(r)[0] else self.refs_for(r.id)
+        return [x for x in refs if not x.is_test]
+
+    def _traced_by(self, r: Req, test: bool) -> bool:
+        """A code marker (or with `test`, a test marker) names `r` — or, where its
+        level must be satisfied, every branch beneath it ends in one: each
+        requirement satisfying it is named, or is in turn satisfied by
+        requirements that all are. One branch without leaves it short, and its
+        progress Partial."""
+        def named(rid: str) -> bool:
+            return any(x.is_test == test for x in self.refs_for(rid))
+
+        def reaches(rid: str, seen: frozenset) -> bool:
+            if named(rid):
+                return True
+            below = [c for c in self.satisfied_by.get(rid, []) if c not in seen]
+            return bool(below) and all(reaches(c, seen | {c}) for c in below)
+        return named(r.id) or (self.needs(r)[0] and reaches(r.id, frozenset({r.id})))
+
+    def coded(self, r: Req) -> bool:
+        """Code names `r`, or every branch beneath it — see `_traced_by`."""
+        return self._traced_by(r, test=False)
+
+    def tested(self, r: Req) -> bool:
+        """A test names `r`, or every branch beneath it — see `_traced_by`."""
+        return self._traced_by(r, test=True)
+
+    def missing(self, r: Req) -> set[str]:
+        """What `r` lacks of what it needs: "satisfied", "code", "test".
+
+        - satisfied: something satisfies it — or, needing code too, code names
+          it itself: it is implemented as it stands, not broken down further.
+        - code: code names it — or, needing to be satisfied, every branch
+          beneath it ends in code (see `coded`).
+        - test: the same, with a test (see `tested`)."""
+        satisfied, code, test = self.needs(r)
+        has_below = bool(self.satisfied_by.get(r.id))
+        own_code = any(not x.is_test for x in self.refs_for(r.id))
+        out = set()
+        if satisfied and not has_below and not (code and own_code):
+            out.add("satisfied")
+        if code and not self.coded(r):
+            out.add("code")
+        if test and not self.tested(r):
+            out.add("test")
+        return out
+
+    def progress(self, rid: str) -> Progress:
+        """How far `rid` is built, judged over it and everything that satisfies it,
+        by what each of them `needs`. A user story is Done once its whole chain is."""
+        if rid in self._progress:
+            return self._progress[rid]
+        below = [self.reqs[x] for x in [rid] + self.down(rid) if x in self.reqs]
+        missing = {r.id: self.missing(r) for r in below}
+        unsatisfied = [r.id for r in below if "satisfied" in missing[r.id]]
+        needs_code = [r.id for r in below if self.needs(r)[1]]
+        needs_test = [r.id for r in below if self.needs(r)[2]]
+        uncoded = [r.id for r in below if "code" in missing[r.id]]
+        untested = [r.id for r in below if "test" in missing[r.id]]
+        if rid in unsatisfied and rid not in uncoded:
+            state = "Unsatisfied"
+        elif needs_code and len(uncoded) == len(needs_code):
+            state = "Not implemented"
+        elif uncoded or unsatisfied:
+            state = "Partial"
+        elif untested:
+            state = "Untested"
+        elif needs_code or needs_test:
+            state = "Done"
+        else:
+            state = ""
+        p = self._progress[rid] = Progress(state, unsatisfied, uncoded, untested)
+        return p
+
     def next_id(self, prefix: str) -> str:
         unit = self.unit(prefix)
         lv = self.cfg.level(unit.level) if unit else None
@@ -234,7 +348,6 @@ class Model:
     def gaps(self) -> dict:
         g = {"dangling": [], "orphans": [], "unsatisfied": [], "untested": [],
              "uncoded": [], "not_accepted": []}
-        parents = self.cfg.parent_kinds
         for r in self.reqs.values():
             lv = self.cfg.level(r.kind)
             for t in r.satisfies:
@@ -242,14 +355,12 @@ class Model:
                     g["dangling"].append({"id": r.id, "missing": t})
             if lv and lv.satisfies and not r.satisfies:
                 g["orphans"].append(r.id)
-            if r.kind in parents and not self.satisfied_by.get(r.id):
-                g["unsatisfied"].append(r.id)
+            missing = self.missing(r)
+            for need, key in (("satisfied", "unsatisfied"), ("test", "untested"), ("code", "uncoded")):
+                if need in missing:
+                    g[key].append(r.id)
             if not self.reviewed(r):
                 continue
-            if self.automated(r) and not [x for x in self.covering_refs(r.id) if x.is_test]:
-                g["untested"].append(r.id)
-            if self.code_bearing(r.id) and not [x for x in self.refs_for(r.id) if not x.is_test]:
-                g["uncoded"].append(r.id)
             if r.status != "Accepted":
                 g["not_accepted"].append(r.id)
         for k in g:

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/themes/README.md

@@ -18,11 +18,11 @@ except `selection`, the one filled row.
 | `heading` | Section headings and numbers in a document |
 | `id` | A requirement or question ID |
 | `link` | An ID in running text, which can be followed |
-| `link_active` | The link under the keyboard cursor, and the preview's border |
+| `link_active` | The link under the keyboard cursor, the preview's border, and `Reloading` in the hint line |
 | `code` | Inline code — byte values, command codes |
 | `table_header` | A table's header row |
 | `statement_bar` | The bar beside a requirement's statement |
-| `accepted` `proposed` `reopened` | Review status |
+| `accepted` `proposed` `reopened` | Review status, and progress: done, part built, not built |
 | `security` | The security-relevant marker |
 | `open` `answered` | An open question's state |
 | `keys` | Key names in the hint line |

{reqdeck-0.1.0 → reqdeck-0.2.0}/reqdeck/viewer.py

@@ -3,7 +3,8 @@ questions beside them. Reads through the same model as the CLI and writes
 through the same operations.
 
 Needs `textual`, which the CLI does not. The chosen theme and sidebar width
-are remembered per user in `$XDG_CONFIG_HOME/reqdeck/tui.json`.
+are remembered per user in `$XDG_CONFIG_HOME/reqdeck/tui.json`, and the seconds
+between reloads read from it: `"reload": 30` by default, `0` for never.
 """
 
 from __future__ import annotations
@@ -37,6 +38,9 @@ TARGET_RE = re.compile(r"(?:goto|link)\('(?:reqdeck:)?([^']+)'\)")
 
 #: Status letter in the tree, and the theme role that colours it.
 STATUS_MARK = {"Accepted": ("A", "accepted"), "Proposed": ("P", "proposed"), "Reopened": ("R", "reopened")}
+#: Progress mark in the tree, and the theme role that colours it.
+PROGRESS_MARK = {"Done": ("✓", "accepted"), "Untested": ("◑", "proposed"), "Partial": ("◔", "proposed"),
+                 "Not implemented": ("○", "reopened"), "Unsatisfied": ("✗", "reopened")}
 
 HELP = """\
 # Keys
@@ -61,11 +65,25 @@ The tree always has the cursor; the reading pane shows what it highlights.
 | `a` | Accept the highlighted requirement |
 | `<` `>` | Narrow or widen the sidebar — or drag the divider |
 | `t` | Theme — previewed as you move, `enter` keeps it |
-| `r` | Reload from disk |
+| `r` | Reload from disk — it also does so every 30 seconds |
 | `q` | Quit |
 
 Every requirement and question ID in the reading pane is a link, and so is every code
 and test reference. Hover one for a preview, click it to go there.
+
+# Marks
+
+Beside each requirement in the tree: its review status, then how far it is built — judged
+over it and everything that satisfies it, from the links and the `@REQ_REF` markers.
+
+| | |
+|---|---|
+| `A` `P` `R` | Accepted, Proposed, Reopened |
+| `✓` | Done — coded, and tested where its verification asks, and so is everything beneath it |
+| `◑` | Untested — the code is there, a test its verification asks for is not |
+| `◔` | Partial — some of what is beneath it is built, not all |
+| `○` | Not implemented — code is expected, and none names it |
+| `✗` | Unsatisfied — a lower level exists to satisfy it, and nothing does |
 """
 
 
@@ -282,6 +300,11 @@ def _status_chip(status: str) -> Content:
     return Content.assemble((f"● {status}", f"bold $rk-{role}"))
 
 
+def _progress_chip(state: str) -> Content:
+    mark, role = PROGRESS_MARK.get(state, ("?", "muted"))
+    return Content.assemble((f"{mark} {state}", f"bold $rk-{role}"))
+
+
 def _link(rid: str, sel: str = "") -> tuple[str, str]:
     """A clickable ID; the one under the keyboard link cursor is drawn reversed."""
     style = "bold $rk-link-active on $rk-selection" if rid == sel else "$rk-link underline"
@@ -371,6 +394,8 @@ def requirement_card(m: Model, r: Req, full: bool, sel: str = "") -> Vertical:
         head += ["  ", (r.title, "bold $rk-foreground")]
     if m.reviewed(r) and r.status:
         head += ["  ", _status_chip(r.status)]
+    if m.progress(r.id).state:
+        head += ["  ", _progress_chip(m.progress(r.id).state)]
     if r.security:
         head += ["  ", ("◆ security", "bold $rk-security")]
     parts.append(Static(Content.assemble(*head), classes="card-head"))
@@ -527,6 +552,12 @@ class ReqdeckApp(App):
         Binding("greater_than_sign", "resize(4)", show=False),
         Binding("q", "quit", "Quit"),
     ]
+    #: Seconds between reloads from disk, unless `tui.json` names its own; 0 is never.
+    RELOAD_EVERY = 30
+    #: Frames of the spinner drawn while a reload runs, as lazygit's.
+    SPINNER = "|/-\\"
+    #: The spinner stays up at least this long, so a fast reload is still seen.
+    SPIN_AT_LEAST = 0.5
 
     def __init__(self):
         # ansi_color leaves the terminal's own background unpainted: with it
@@ -546,6 +577,10 @@ class ReqdeckApp(App):
         self.hovering = ""
         self.back: list[tuple] = []
         self.forward: list[tuple] = []
+        #: The spinner's frame while a reload runs; None when none does.
+        self._spin: int | None = None
+        #: The last reload's error, so a file left broken is reported once.
+        self._reload_error = ""
         self.prefs = load_prefs()
         self.palettes = themes.load_all()
         for p in self.palettes.values():
@@ -584,6 +619,12 @@ class ReqdeckApp(App):
         self.show(("help", None))
         self.refresh_keys()
         self.run_worker(self._warm_origins, thread=True, group="warm")
+        try:
+            every = float(self.prefs.get("reload", self.RELOAD_EVERY))
+        except (TypeError, ValueError):
+            every = self.RELOAD_EVERY
+        if every > 0:
+            self.set_interval(every, self.reload)
 
     def _warm_origins(self) -> None:
         """What every reference is attached to, read in a thread at start, so a
@@ -666,6 +707,9 @@ class ReqdeckApp(App):
             if i:
                 parts.append(("  |  ", "$rk-muted"))
             parts += [(f"{action}: ", "$rk-muted"), (key, "bold $rk-keys")]
+        if self._spin is not None:
+            frame = self.SPINNER[self._spin % len(self.SPINNER)]
+            parts = [(f"Reloading {frame}", "bold $rk-link-active"), "    "] + parts
         line = Content.assemble(*parts)
         if str(line) != str(bar.content):           # a repaint only when it changed
             bar.update(line)
@@ -686,6 +730,12 @@ class ReqdeckApp(App):
         if self.m.reviewed(r):
             mark, role = STATUS_MARK.get(r.status, ("?", "muted"))
             t.append(f"{mark} ", style=f"bold {self.colour(role)}")
+        state = self.m.progress(r.id).state
+        if state:
+            mark, role = PROGRESS_MARK[state]
+            t.append(f"{mark} ", style=f"bold {self.colour(role)}")
+        else:
+            t.append("  ")
         t.append(r.id, style=self.colour("id"))
         t.append(f"  {r.label}")
         return t
@@ -782,6 +832,8 @@ class ReqdeckApp(App):
 
     @on(Tree.NodeHighlighted)
     def _highlighted(self, event: Tree.NodeHighlighted) -> None:
+        if event.node.data == self.shown:
+            return              # the tree rebuilt under a view it already shows
         self.show(event.node.data)
 
     def _widgets_for(self, data, sel: str = "") -> list[Widget]:
@@ -818,12 +870,16 @@ class ReqdeckApp(App):
             return out
         if kind == "level":
             lv = m.cfg.level(key)
+            def done(u) -> str:
+                states = [m.progress(r.id).state for r in m.reqs.values() if r.unit == u.stem]
+                asked = [st for st in states if st]
+                return f"{asked.count('Done')}/{len(asked)}" if asked else "—"
             rows = "\n".join(
                 f"| {u.title} | `{', '.join(u.prefixes)}` | {sum(1 for r in m.reqs.values() if r.unit == u.stem)} "
-                f"| `{m.cfg.rel(u.csv_path)}` |" for u in m.units if u.level == key)
+                f"| {done(u)} | `{m.cfg.rel(u.csv_path)}` |" for u in m.units if u.level == key)
             return [heading(f"{lv.kind} — {lv.title}", 1),
                     Markdown(f"Satisfies: **{', '.join(lv.satisfies) or 'top level'}**\n\n"
-                             f"| Unit | Prefix | Requirements | File |\n|---|---|---|---|\n{rows}\n",
+                             f"| Unit | Prefix | Requirements | Done | File |\n|---|---|---|---|---|\n{rows}\n",
                              classes="prose")]
         if kind == "topic":
             qs = [q for q in m.questions if q.topic == key]
@@ -945,6 +1001,8 @@ class ReqdeckApp(App):
             head = [(r.id, "bold $rk-id")] + (["  ", (r.title, "bold $rk-foreground")] if r.title else [])
             if m.reviewed(r) and r.status:
                 head += ["  ", _status_chip(r.status)]
+            if m.progress(r.id).state:
+                head += ["  ", _progress_chip(m.progress(r.id).state)]
         else:
             head = [(self._title_for(data), "bold $rk-heading")]
         top = Static(Content.assemble(*head), classes="card-head")
@@ -1005,12 +1063,66 @@ class ReqdeckApp(App):
     def action_help(self) -> None:
         self.show(("help", None))
 
-    def action_reload(self, quiet: bool = False) -> None:
-        self.m = load_model()
-        self.relabel()          # rebuilds the tree, keeping the cursor where it was
-        if not quiet:
+    def action_reload(self) -> None:
+        self.reload(say=True)
+
+    def reload(self, say: bool = False) -> None:
+        """Read the model from disk again, in a thread, with the spinner up meanwhile.
+        A dialog defers it: the next one comes soon enough."""
+        if self._spin is not None or len(self.screen_stack) > 1:
+            return
+        self._spin = 0
+        self.refresh_keys()
+        self.run_worker(self._reload(say), exclusive=True, group="reload")
+
+    async def _reload(self, say: bool) -> None:
+        start = time.monotonic()
+        ticker = self.set_interval(0.1, self._spin_on)
+        try:
+            m, error = await asyncio.to_thread(load_model), ""
+        except Exception as e:      # a broken config or file, maybe half written
+            m, error = None, str(e)
+        await asyncio.sleep(max(0.0, self.SPIN_AT_LEAST - (time.monotonic() - start)))
+        ticker.stop()
+        self._spin = None
+        self.refresh_keys()
+        if error:
+            if say or error != self._reload_error:
+                self.notify(error, title="Reload failed", severity="error")
+            self._reload_error = error
+            return
+        self._reload_error = ""
+        if len(self.screen_stack) == 1 and not self._same(m, self.m):
+            self.m = m
+            self.drop_link()
+            self.relabel()          # rebuilds the tree, keeping the cursor where it was
+            here = self.shown
+            if here and (here[0] == "help" or self._node_for(here) is not None):
+                # Redrawn from the new model, scrolled where it was.
+                self.links = self._links_for(here) if here[0] in ("unit", "section") else None
+                self.show(here, keep=True)
+            else:
+                self.call_after_refresh(self._show_cursor)     # it is gone
+        if say:
             self.notify("Reloaded")
 
+    def _show_cursor(self) -> None:
+        node = self.query_one("#nav", Tree).cursor_node
+        if node is not None:
+            self.show(node.data)
+
+    def _spin_on(self) -> None:
+        if self._spin is not None:
+            self._spin += 1
+            self.refresh_keys()
+
+    @staticmethod
+    def _same(a: Model, b: Model) -> bool:
+        """Nothing on disk changed between two loads, so nothing need be redrawn."""
+        def facts(m: Model) -> tuple:
+            return m.cfg, m.units, m.reqs, m.refs, m.topics, m.questions, m.load_problems
+        return facts(a) == facts(b)
+
     def action_next_match(self, direction: int) -> None:
         tree = self.query_one("#nav", Tree)
         line = tree.cursor_line
@@ -1085,6 +1197,8 @@ class ReqdeckApp(App):
                 head += ["  ", (r.title, "bold")]
             if m.reviewed(r) and r.status:
                 head += ["  ", _status_chip(r.status)]
+            if m.progress(r.id).state:
+                head += ["  ", _progress_chip(m.progress(r.id).state)]
             lines = [Content.assemble(*head), Content(""), Content(r.statement)]
             if r.satisfies:
                 lines.append(Content.assemble(("Satisfies  ", "$rk-muted"), ", ".join(r.satisfies)))
@@ -1301,7 +1415,7 @@ class ReqdeckApp(App):
             if terminal:
                 with self.suspend():
                     subprocess.run(argv, cwd=self.m.cfg.root)
-                self.action_reload(quiet=True)
+                self.reload()
             else:
                 subprocess.Popen(argv, cwd=self.m.cfg.root, stdin=subprocess.DEVNULL,
                                  stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,

{reqdeck-0.1.0 → reqdeck-0.2.0}/skills/reqdeck-cli/SKILL.md

@@ -148,10 +148,31 @@ non-canonical CSV, a detail block for a requirement that is not in that unit, an
 | `dangling` | Satisfies something that does not exist — always a bug |
 | `orphans` | No satisfies link. Legitimate only with the reason in the rationale |
 | `unsatisfied` | A story, or a parent level, nothing satisfies yet |
-| `untested` | Verification is automated, but no test names it or anything beneath it |
-| `uncoded` | Unit has `code = true`, but no code names it |
+| `untested` | Its level, or else its verification method, needs a test, and no test names it — or, where it must be satisfied, not every requirement beneath it |
+| `uncoded` | Its level, or else its unit, needs code, and no code names it — or, where it must be satisfied, not every requirement beneath it |
 | `not_accepted` | Awaiting the user's review — not a gap to close by editing |
 
+What each level needs is set by `satisfied`, `code` and `test` on its `[[levels]]` entry in
+`.reqdeck.toml`:
+
+- `satisfied` — something beneath satisfies it, or, where the level also needs code, code
+  names it itself.
+- `code` — code names it, or, where the level also needs satisfying, code names every
+  requirement beneath it (each one, or all of the ones satisfying it in turn). One branch
+  without code leaves it uncoded.
+- `test` — the same as `code`, with tests: a test names it, or, where the level also needs
+  satisfying, a test names every requirement beneath it.
+
+So a requirement that needs both `satisfied` and `code` is done broken down (lower
+requirements satisfy it, and code names every one of them) or implemented as it stands (code
+names it directly). Put a marker on the requirement the code really implements; never add one to a
+higher level just to close its gap.
+
+`get --json` carries the same per requirement as `progress`, judged over it and everything
+beneath it: `state` is `Unsatisfied`, `Not implemented`, `Partial`, `Untested` or `Done`
+(empty where nothing traceable is asked), and `unsatisfied`, `uncoded`, `untested` list the
+IDs keeping it from `Done`. A story is `Done` only once its whole chain is.
+
 Gaps are normal while topics are still being discussed. **Do not close them by inventing
 links or markers.** Report them.
 

{reqdeck-0.1.0 → reqdeck-0.2.0}/tests/test_reqdeck.py

@@ -250,6 +250,94 @@ class TestTrace(Base):
         self.assertEqual([r.id for r in m.covering_refs("SR_001")], ["SSR_APP_001"])
         self.assertNotIn("SR_001", m.gaps()["untested"])
 
+    def test_every_branch_beneath_needs_its_test(self):
+        self.p.write("tests/screen_test.swift", "// @REQ_REF(SSR_APP_001) shows the screen\n")
+        ops.add(self.p.model(), "SSR_APP", {"statement": "T.", "satisfies": "SR_001", "source": "x",
+                                            "verification": "T"})
+        m = self.p.model()
+        self.assertIn("SR_001", m.gaps()["untested"])                 # SSR_APP_002 has no test
+        self.p.write("tests/sound_test.swift", "// @REQ_REF(SSR_APP_002) sounds\n")
+        self.assertNotIn("SR_001", self.p.model().gaps()["untested"])
+
+    def test_progress_rolls_up_the_chain(self):
+        def states():
+            m = self.p.model()
+            return [m.progress(rid).state for rid in ("A-01", "SR_001", "SSR_APP_001")]
+        self.assertEqual(states(), ["Not implemented"] * 3)
+        self.p.write("src/screen.swift", "// @REQ_REF(SSR_APP_001) shows the screen\n")
+        self.assertEqual(states(), ["Untested"] * 3)
+        self.assertEqual(self.p.model().progress("A-01").untested, ["SR_001", "SSR_APP_001"])
+        self.p.write("tests/screen_test.swift", "// @REQ_REF(SSR_APP_001) shows the screen\n")
+        self.assertEqual(states(), ["Done"] * 3)
+        # A second story, which nothing satisfies, and a second child with no code.
+        ops.add(self.p.model(), "A", {"statement": "As a collector, I want sound."})
+        ops.add(self.p.model(), "SSR_APP", {"statement": "T.", "satisfies": "SR_001", "source": "x",
+                                            "verification": "I"})
+        m = self.p.model()
+        self.assertEqual(m.progress("A-02").state, "Unsatisfied")
+        self.assertEqual(m.progress("SR_001").state, "Partial")
+        self.assertEqual(m.progress("SR_001").uncoded, ["SSR_APP_002"])
+
+
+class TestLevelNeeds(Base):
+    def configure(self, sr: str) -> None:
+        """The SR level with `sr` in place of `traced = false`."""
+        path = self.p.root / ".reqdeck.toml"
+        path.write_text(CONFIG.replace("topic = true\ntraced = false\n", f"topic = true\n{sr}\n", 1))
+
+    def test_its_own_code_or_code_on_every_branch_beneath(self):
+        self.configure("code = true")
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"satisfied", "code", "test"})
+        self.assertEqual(m.progress("SR_001").state, "Not implemented")
+        self.p.write("src/light.swift", "// @REQ_REF(SR_001) lights\n")
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"test"})        # coded: no breakdown needed
+        self.p.write("src/light.swift", "")
+        ops.add(self.p.model(), "SSR_APP", {"statement": "S.", "satisfies": "SR_001", "source": "x",
+                                            "verification": "I"})
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"code", "test"})  # broken down, but nothing coded
+        self.p.write("src/screen.swift", "// @REQ_REF(SSR_APP_001) shows it\n")
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"test"})        # code beneath it counts
+        self.assertEqual([x.id for x in m.code_refs(m.reqs["SR_001"])], ["SSR_APP_001"])
+        ops.add(self.p.model(), "SSR_APP", {"statement": "T.", "satisfies": "SR_001", "source": "x",
+                                            "verification": "I"})
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"code", "test"})  # every branch must end in code
+        self.assertEqual(m.progress("SR_001").state, "Partial")
+        self.p.write("src/sound.swift", "// @REQ_REF(SSR_APP_002) sounds\n")
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), {"test"})
+
+    def test_code_beneath_counts_only_where_it_must_be_satisfied(self):
+        self.configure("satisfied = false\ncode = true")
+        ops.add(self.p.model(), "SSR_APP", {"statement": "S.", "satisfies": "SR_001", "source": "x",
+                                            "verification": "I"})
+        self.p.write("src/screen.swift", "// @REQ_REF(SSR_APP_001) shows it\n")
+        m = self.p.model()
+        self.assertIn("code", m.missing(m.reqs["SR_001"]))           # only its own marker counts
+        self.configure("traced = false\ncode = true")                   # met only from beneath: fine
+        self.assertEqual(self.p.model().missing(self.p.model().reqs["SR_001"]), {"test"})
+        self.configure("traced = false\ncode = true\nsatisfied = false")
+        with self.assertRaisesRegex(config.ConfigError, "needs satisfied = true"):
+            self.p.model()
+
+    def test_levels_turn_needs_off(self):
+        self.configure("traced = false\nsatisfied = false\ntest = false")
+        m = self.p.model()
+        self.assertEqual(m.missing(m.reqs["SR_001"]), set())
+        self.assertNotIn("SR_001", m.gaps()["unsatisfied"])
+        self.assertNotIn("SR_001", m.gaps()["untested"])
+
+    def test_contradictions_are_refused(self):
+        self.configure("")
+        path = self.p.root / ".reqdeck.toml"
+        path.write_text(path.read_text().replace('kind = "SSR"\n', 'kind = "SSR"\nsatisfied = true\n'))
+        with self.assertRaisesRegex(config.ConfigError, "no level names SSR"):
+            self.p.model()
+
 
 class TestDocument(Base):
     def test_sections_are_numbered_by_declaration_order(self):

{reqdeck-0.1.0 → reqdeck-0.2.0}/tests/test_tui.py

@@ -361,6 +361,45 @@ class TuiTest(unittest.TestCase):
         self.run_app(steps)
         self.assertEqual(self.p.model().reqs["SR_002"].status, "Accepted")
 
+    def test_reload_spins_while_it_runs_and_redraws_only_a_change(self):
+        async def steps(app, pilot):
+            bar = app.query_one("#keys")
+            self.assertNotIn("Reloading", str(bar.content))
+            app.action_goto("SR_002")
+            await self.settle(app, pilot)
+            page = app._page()
+            app.reload()
+            await pilot.pause()
+            self.assertTrue(str(bar.content).startswith("Reloading |"))
+            await self.settle(app, pilot)
+            self.assertNotIn("Reloading", str(bar.content))
+            self.assertIs(app._page(), page)            # nothing changed: nothing redrawn
+
+            ops.edit(self.p.model(), "SR_002", {"title": "Shine"})
+            app.reload()
+            await self.settle(app, pilot)
+            self.assertEqual(self.cursor(app), ("req", "SR_002"))
+            self.assertIn("Shine", str(app._page().query_one(".card-head").content))
+        self.run_app(steps)
+
+    def test_reload_runs_on_its_own_unless_turned_off(self):
+        from reqdeck.viewer import ReqdeckApp, save_prefs
+
+        async def go(prefs):
+            save_prefs(prefs)
+            app = ReqdeckApp()
+            app.SPIN_AT_LEAST = 0
+            async with app.run_test(size=(160, 48)) as pilot:
+                await pilot.pause()
+                rid, _, _ = ops.add(self.p.model(), "SR", {
+                    "title": "Hum", "statement": "The system shall hum.", "satisfies": "A-01",
+                    "topic": "01", "source": "OQ-0102.", "verification": "T"})
+                await asyncio.sleep(0.5)            # a tick after the change, at least
+                await self.settle(app, pilot)
+                return rid in app.nodes
+        self.assertTrue(asyncio.run(go({"reload": 0.1})))
+        self.assertFalse(asyncio.run(go({"reload": 0})))
+
 
 if __name__ == "__main__":
     unittest.main()