reqdeck 0.1.0__py3-none-any.whl

reqdeck/render.py

@@ -0,0 +1,140 @@
+"""Markdown views of the model, shared by `reqdeck doc --markdown` and the TUI."""
+
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+
+from .model import Model, Req
+from .questions import Question
+from .store import Unit
+
+
+def _meta(m: Model, r: Req) -> list[str]:
+    meta = []
+    if r.rationale:
+        meta.append(f"*Rationale:* {r.rationale}")
+    if r.satisfies:
+        meta.append(f"*Satisfies:* {', '.join(r.satisfies)}")
+    if r.topics:
+        meta.append("*Topic:* " + ", ".join(f"{t} {m.topics.get(t, '?')}" for t in r.topics))
+    if r.source:
+        meta.append(f"*Source:* {r.source}")
+    for k, v in r.extra.items():
+        meta.append(f"*{k.capitalize()}:* {v}")
+    bits = []
+    if r.verification:
+        v = m.cfg.verification.get(r.verification)
+        bits.append(f"*Verification:* {r.verification}" + (f" — {v.name}" if v else ""))
+    if r.status:
+        bits.append(f"*Status:* {r.status}")
+    if r.security:
+        bits.append("*Security relevant*")
+    if bits:
+        meta.append(" · ".join(bits))
+    return meta
+
+
+def requirement(m: Model, r: Req, heading: str = "##", chain: bool = False) -> str:
+    out = [f"{heading} {r.id}" + (f" — {r.title}" if r.title else ""), "", r.statement, ""]
+    if r.detail:
+        out += [r.detail, ""]
+    meta = _meta(m, r)
+    if meta:
+        out += ["  \n".join(meta), ""]
+    if chain:
+        up = [f"- {t} — {m.reqs[t].label if t in m.reqs else '(undefined)'}" for t in r.satisfies]
+        down = [f"- {t} — {m.reqs[t].label}" for t in m.satisfied_by.get(r.id, [])]
+        out += ["**Satisfies**", ""] + (up or ["- nothing"]) + [""]
+        out += ["**Satisfied by**", ""] + (down or ["- nothing yet"]) + [""]
+        refs = m.refs_for(r.id)
+        if refs:
+            out += ["**References**", ""]
+            out += [f"- `{x.file}:{x.line}` {'test' if x.is_test else 'code'} — {x.note}" for x in refs]
+            out.append("")
+        out.append(f"`{r.file}:{r.line}`")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def document(m: Model, unit: Unit) -> str:
+    out = [f"# {unit.title}", ""]
+    if unit.description:
+        out += [unit.description, ""]
+    for e in m.document(unit):
+        if e["type"] == "section":
+            s = e["section"]
+            out += [f"{'#' * min(e['depth'] + 1, 6)} {e['number']} {s.title}", ""]
+            if s.description:
+                out += [s.description, ""]
+        else:
+            out += [requirement(m, e["req"], heading="######")]
+    return "\n".join(out).rstrip() + "\n"
+
+
+def question(q: Question, topic_title: str) -> str:
+    out = [f"## {q.id} — {q.title}", "", f"*Topic {q.topic} — {topic_title}*", "",
+           "**Question**", "", q.question or "—", "",
+           "**Answer**", "", q.answer or "*Open.*", ""]
+    if q.blocks:
+        out += ["**Blocks**", "", q.blocks, ""]
+    return "\n".join(out)
+
+
+def excerpt(root: Path, file: str, line: int, before: int = 3, after: int = 8) -> list[tuple[int, str]]:
+    """Numbered source lines around `line` of `file`, which is relative to `root`."""
+    try:
+        lines = (root / file).read_text(errors="replace").splitlines()
+    except OSError:
+        return []
+    start = max(1, line - before)
+    return [(n, lines[n - 1]) for n in range(start, min(len(lines), line + after) + 1)]
+
+
+COMMENT = ("//", "/*", "*", "#", '"""', "'''", "--", "///")
+
+
+def origin(root: Path, file: str, line: int) -> str:
+    """What the marker at `line` is attached to: the first line of code after its
+    comment, or "file header" when the comment is the file's own @file block."""
+    try:
+        mtime = (root / file).stat().st_mtime_ns
+    except OSError:
+        return ""
+    _seen.add((root, file, line, mtime))
+    return _origin(root, file, line, mtime)
+
+
+def origin_cached(root: Path, file: str, line: int) -> bool:
+    """Whether `origin` would answer without reading the file."""
+    try:
+        mtime = (root / file).stat().st_mtime_ns
+    except OSError:
+        return True
+    key = (root, file, line, mtime)
+    return key in _seen
+
+
+_seen: set = set()
+
+
+@functools.lru_cache(maxsize=4096)
+def _origin(root: Path, file: str, line: int, mtime: int) -> str:
+    """`origin`, cached until the file changes."""
+    try:
+        lines = (root / file).read_text(errors="replace").splitlines()
+    except OSError:
+        return ""
+    # The comment block the marker sits in, upwards then downwards.
+    start = line - 1
+    while start > 0 and lines[start - 1].strip().startswith(COMMENT):
+        start -= 1
+    block = lines[start:line]
+    end = line
+    while end < len(lines) and (not lines[end].strip() or lines[end].strip().startswith(COMMENT)):
+        block.append(lines[end])
+        end += 1
+    if any("@file" in b for b in block):
+        return "file header"
+    code = lines[end].strip() if end < len(lines) else ""
+    code = code.rstrip("{").rstrip()
+    return code if len(code) <= 72 else code[:71] + "…"

reqdeck/skills/reqdeck-cli/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: reqdeck-cli
+description: Query, add, edit and validate requirements and open questions with the reqdeck CLI. Use when looking up which requirement covers a behaviour, before implementing or changing a feature, when writing or reviewing a test, adding @REQ_REF markers, writing new requirements, checking traceability, listing open questions, or before claiming work is complete. Applies in any repository with a .reqdeck.toml.
+---
+
+# reqdeck — the CLI
+
+A project using reqdeck has `.reqdeck.toml` in its root, and reqdeck installed
+(`pip install reqdeck`, usually in the project's venv). Run it from anywhere inside the
+project:
+
+```bash
+reqdeck --json get TSR_009
+```
+
+If `reqdeck` is not on the path, `python3 -m reqdeck` is the same command. Every command
+takes `--json`; prefer it, since it is stable and carries the transitive chain the
+human-readable form draws as a tree.
+
+The method behind the files — levels, how a requirement is written, the open-question
+workflow, `@REQ_REF` rules — is the **reqdeck-method** skill. This one is the tool.
+
+## The files
+
+Requirements live in the folder `.reqdeck.toml` names, one *unit* per prefix:
+
+| File | Holds | Edit with |
+|---|---|---|
+| `<unit>.csv` | One requirement per row, ordered by ID, append-only | `reqdeck add`, `reqdeck edit` — never by hand |
+| `<unit>.toml` | Level, prefix, title, description, `code`, sections | By hand |
+| `<unit>.details.md` | Multi-line detail — tables, layouts — one `## <ID>` each | By hand |
+
+**Never edit a CSV by hand.** Quoting is easy to break, a hand edit can set a status the
+tool would refuse, and `check` rejects any file not in the exact form the tool writes. If a
+CSV has been edited outside the tool, `reqdeck fmt` rewrites it canonically.
+
+Open questions live in markdown (`questions =` in `.reqdeck.toml`) and are edited by hand.
+
+## Commands
+
+| | |
+|---|---|
+| `get <ID>` | One requirement with its chain up and down, detail, code and test refs |
+| `search <regex>` | Over id, title, statement, rationale and detail |
+| `list [--kind --unit --topic --section --verification --status --security] [-l]` | Filtered inventory |
+| `tree <ID> [--up\|--down]` | Just the chain |
+| `doc <unit> [--markdown]` | A unit as a document, sections numbered |
+| `levels` | Levels, and the units in each |
+| `topics` | Every topic: open and answered questions, requirement count |
+| `questions [--topic NN] [--open\|--answered] [-l]` | The open questions |
+| `coverage` | Where traceability is missing |
+| `trace <ID>...` | Are these referenced from code and tests? Exit 1 if not |
+| `check` | Validate everything. **Exit 1 on any problem** |
+| `verification` | The verification methods this project uses |
+| `add <PREFIX> ...` | Allocate the next ID and append a requirement |
+| `edit <ID> --<field> ...` | Change fields of an existing requirement |
+| `unit <file> --level --prefix --title [--code]` | Create a new unit |
+| `fmt` | Rewrite the CSVs in canonical form |
+| `url <ID>...` | Link to the requirement's row on GitHub, for an issue |
+
+## Before implementing anything
+
+Find what governs it, and read the statement before writing code:
+
+```bash
+reqdeck --json search 'keyframe|interpolat'
+reqdeck --json get TSSR_FWN_012
+```
+
+If nothing matches, that is a finding — say so rather than inventing behaviour.
+
+## Adding a requirement
+
+**A new ID comes from `add`, never from typing one.** It allocates the next number, finds
+the unit holding the prefix, validates every link, and writes `Proposed` — it has no way
+to write anything else.
+
+```bash
+reqdeck add TSSR_FWN --title "Channel PWM" \
+    --statement "The Node shall drive each channel with 12-bit PWM at 1 kHz." \
+    --satisfies TSR_025,TSR_026 --topic 06 --source "OQ-0608." --verification S \
+    [--rationale "..."] [--section render.pwm] [--security]
+```
+
+- `--topic` is required on levels that set `topic = true`; it must be a topic in
+  OPEN-QUESTIONS.
+- `--satisfies` must name existing requirements of a level this one may satisfy.
+- `--section` must be a key declared in the unit's `.toml`. Add the section there first.
+- A column the unit has beyond the standard ones: `--field <column> <value>`.
+- Stories: `add A --statement "As a …"` — no source, verification or status.
+
+It refuses a prefix no unit holds. A new prefix is a new unit of the design — create it
+deliberately with `reqdeck unit`, and only when the user has agreed the unit exists.
+
+Multi-line detail does not go in the CSV. Append a block to `<unit>.details.md`:
+
+```markdown
+## ICD_BUS_014
+
+| Off | Len | Field | Notes |
+|---|---|---|---|
+| 0 | 1 | Form and count | ... |
+```
+
+## Changing a requirement
+
+```bash
+reqdeck edit TSR_009 --statement "..." --source "OQ-0507. Reopened 2026-10-10 by OQ-0512: ..."
+```
+
+`edit` changes any field but `id` and `status`. **Changing an Accepted requirement turns
+it Reopened automatically** — say what changed and why in `source`. Nothing in the CLI
+sets `Accepted`: only the user does, in the TUI (`reqdeck tui`, key `a`) or by hand.
+Never work around that.
+
+IDs are permanent. Never renumber, never reuse a retired ID, never delete a row that code,
+tests or issues may point at.
+
+## Sections
+
+A requirement's `section` is a stable key; numbers are derived from declaration order in
+the unit's `.toml`, so inserting a section never touches a row:
+
+```toml
+[[sections]]
+key = "power"
+title = "Power"
+
+[[sections]]
+key = "power.bus"            # nests under power: shown as 1.1
+title = "Bus supply"
+description = "What the cable carries."
+```
+
+Reorder or insert by editing the `.toml`. Move a requirement with `edit --section`.
+
+## Interpreting `check` and `coverage`
+
+`check` fails on anything structurally wrong: a dangling link, a link to the wrong level, a
+duplicate ID, a malformed ID, a missing required field, an undeclared section or topic, a
+non-canonical CSV, a detail block for a requirement that is not in that unit, and every
+`@REQ_REF` rule. It prints the status tally and never fails on it.
+
+`coverage` reports work not yet done:
+
+| | |
+|---|---|
+| `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 |
+| `not_accepted` | Awaiting the user's review — not a gap to close by editing |
+
+Gaps are normal while topics are still being discussed. **Do not close them by inventing
+links or markers.** Report them.
+
+## Before claiming work is complete
+
+```bash
+reqdeck trace TSSR_FWN_012 ICD_BUS_014   # what the change claims to implement
+reqdeck check
+```
+
+`trace` refuses a level marked `traced = false` (typically the system level) and names
+what satisfies it instead: a task names the level that reaches code.

reqdeck/skills/reqdeck-method/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: reqdeck-method
+description: The reqdeck way of designing a product with its user — product brief, topics, open questions answered one at a time, then requirements derived from the answers, traced to code and tests with @REQ_REF. Use when setting up a new project for requirements, starting or continuing design work, discussing or answering an open question, writing or reviewing requirements, deciding a requirement's level, or adding @REQ_REF markers to code and tests.
+---
+
+# The reqdeck method
+
+A design is built *with* the user, not for them. The agent researches, drafts, lays out
+options and recommends; **the user decides**. Every requirement traces to a decision the
+user actually made, and the files record which requirements the user has actually read.
+
+The tool is the **reqdeck-cli** skill. Two references go with this file — read them when the
+work reaches them:
+
+- [references/writing-requirements.md](references/writing-requirements.md) — levels,
+  fields, how a statement is written, verification methods, status.
+- [references/markers.md](references/markers.md) — `@REQ_REF` in code and tests.
+
+## The rules that matter most
+
+**Do not invent requirements.** A requirement carries a `source` naming what decided it —
+an answered question, an ADR, a dated choice by the user. If you cannot write that source,
+it is not a requirement: it is a question, and it goes in OPEN-QUESTIONS. **A number
+nobody chose is not a requirement either.** "At least 50 channels" is a requirement only
+if the user chose 50.
+
+**OPEN-QUESTIONS is the source of truth.** Requirements are derived from answered
+questions; architecture notes, ADRs, READMEs and agent instructions restate them and go
+stale. When a document disagrees with an answered question, the question is right and the
+document is wrong — fix the document. Check a requirement against the question that
+produced it rather than assuming it kept up.
+
+**Never set a requirement to `Accepted`.** One you write is `Proposed`; one you change
+that was `Accepted` becomes `Reopened`. Only the user accepts, after reading. An agent that
+accepts its own work destroys the one signal recording what a human has reviewed. The CLI
+cannot write `Accepted`; do not get around it.
+
+**Work topic by topic.** Requirements for a topic are written after the topic is
+discussed, not before.
+
+**Ask rather than assume** when a decision would materially change the design. Give a
+recommendation; let the user decide.
+
+**A risk is not an open question.** A question is undecided and gets decided. A risk may
+happen whatever is decided, and gets watched — in a risk register, not as a question.
+
+## Phase 0 — Setting up
+
+1. Install reqdeck: `pip install reqdeck`, in the project's venv if it has one.
+2. Before running the setup, agree with the user what the parts of the product are. The
+   setup asks for the *shape* of the requirement tree — see
+   [writing-requirements.md](references/writing-requirements.md#levels) — and for one unit
+   per part (firmware, hardware, app, an interface between two of them). It is fine to
+   start with fewer units; `reqdeck unit` adds one later.
+3. Run `reqdeck init` from the project root. It is interactive: relay each question to
+   the user rather than answering it yourself, or have the user run it. It writes
+   `.reqdeck.toml`, creates the units and OPEN-QUESTIONS, and copies both skills into
+   `.claude/skills/` and `.agents/skills/` for Claude Code and Codex. Commit them with the
+   project; after upgrading reqdeck, `reqdeck skills --update` refreshes them.
+4. Record in the project's agent instructions (`AGENTS.md` / `CLAUDE.md`) that the project
+   uses reqdeck and this method, and which topics are complete as that changes.
+
+## Phase 1 — Product brief
+
+A short document: what the product is, for whom, the problem it solves, what it
+deliberately is not, and what would make it a success. Draft it from conversation, then
+let the user correct it. Keep it short — a page, not a spec. Everything later is checked
+against it.
+
+## Phase 2 — Personas and user stories
+
+Personas are short prose in a product document: who they are, what they are comfortable
+with, what they buy, what to avoid. User stories are the root of the requirement tree and
+live in the stories unit, one row each:
+
+```bash
+reqdeck add A --statement "As a collector, I want to turn the display on from my phone, so that I don't have to reach behind the shelf."
+```
+
+One story prefix per persona (`A-01`, `B-01`). Story IDs are permanent. If you drafted the
+stories, say so, and make "are these stories real?" the first open question.
+
+## Phase 3 — Topics
+
+Agree with the user the list of areas where design decisions are needed, and write each as
+a topic in OPEN-QUESTIONS:
+
+```markdown
+## Topic 04 — Bus physical layer
+```
+
+Topics are numbered `01`–`99` and never renumbered. Typical topics: scope and market,
+scale, each interface, each part's hardware and software, power, mechanical, verification,
+compliance, security. Topics are a way to cut the work into sessions, so a topic should be
+discussable in a few sittings.
+
+## Phase 4 — Finding the open questions
+
+For each topic, find the questions *with* the user. A question is something undecided
+whose answer changes the design. While collecting, do not answer:
+
+```markdown
+### OQ-0403 — Connector
+**Question:** Which connector joins a Node to the bus, given the 2 mm pitch of the bricks?
+**Answer:**
+**Blocks:** Rev A layout, TSSR_HWB
+```
+
+IDs are `OQ-TTNN`: topic, then the next free number within it. **Questions never move**,
+and are never deleted — an answered one stays where it is. `Blocks` says what waits on it,
+so the order to answer them in is visible.
+
+```bash
+reqdeck topics              # open and answered per topic
+reqdeck questions --open --topic 04 -l
+```
+
+## Phase 5 — Answering, one question at a time
+
+One question, or a few tightly related ones, per session. For each:
+
+1. **Read what is already decided.** Answered questions in this and neighbouring topics,
+   and requirements already derived from them.
+2. **Research.** Datasheets, prior art, the market, standards, the existing code. Check
+   facts rather than recalling them; stock, prices and versions change.
+3. **Lay out the options** with their trade-offs, and **recommend one**. Say what would
+   change your recommendation.
+4. **The user decides.** Do not write an answer the user has not given.
+5. **Write the answer in place**, with the date and the reasoning a later reader needs:
+   `**Chosen 2026-08-16.** JST SH, because …`. Expensive decisions get an ADR as well.
+6. **New questions** surfaced while answering are added to their topic, not answered in
+   passing. A consequence that may hit whatever is decided is a risk.
+7. **Fix downstream documents** that the answer contradicts.
+
+## Phase 6 — Requirements from a finished topic
+
+When a topic's questions are answered, derive its requirements — see
+[writing-requirements.md](references/writing-requirements.md). Each takes its `source`
+from the answers and its `topic` from the topic, and is written with `reqdeck add`.
+
+Writing requirements finds gaps: a number nobody chose, a behaviour no answer covers, a
+parent that does not exist yet. **Each gap becomes a new open question**, not a
+requirement with an invented value. Tell the user what you found.
+
+Then the user reviews. They read the `Proposed` requirements and accept them in the TUI:
+
+```bash
+reqdeck list --status proposed --topic 06
+reqdeck tui
+```
+
+## Phase 7 — Building it
+
+Work is tracked as tasks that name the requirements they implement — at the level that
+reaches code, never a level marked `traced = false`. Code and tests carry `@REQ_REF`
+markers ([markers.md](references/markers.md)); `reqdeck trace` decides whether a change left
+what it claims traced, and `reqdeck coverage` is the measure of progress, not task counts.
+
+A change in behaviour that no requirement covers is a finding. Raise it as a question
+rather than shipping unspecified behaviour.
+
+## Documents in general
+
+Minimum needed to understand the content. No status badges, progress tracking or
+"to be written" placeholders. Describe only the current state — never what moved or what
+used to be there; git holds the history.

reqdeck/skills/reqdeck-method/references/markers.md

@@ -0,0 +1,92 @@
+# `@REQ_REF` — referencing requirements from code and tests
+
+`reqdeck` scans the source tree for markers and links them to requirements. That link is
+what makes `coverage` and `trace` statements about the code rather than about intentions.
+
+```
+@REQ_REF(<ID>) <a few words on what the requirement asks for>
+```
+
+## The rules
+
+**One ID per marker, and a description after it.** A marker naming three requirements
+reads as one obligation and hides that the three may have diverged; and source read on its
+own should say roughly what it owes, without the requirement file open beside it. Three
+requirements means three lines.
+
+**On the code that implements the requirement — never on an interface.** A requirement is
+discharged by the implementation, not by a declaration of intent, and an interface with
+two implementations would otherwise claim the requirement twice while satisfying it once.
+File stems listed in `interface_suffixes` are rejected.
+
+**Once, on the declaration.** Where a language splits declaration and implementation (C,
+C++, Objective-C), the marker goes on the header and never also in the `.c` — a promise
+restated in two places is one that can disagree. `declaration_extensions` in
+`.reqdeck.toml` enforces this; languages with one file per type (Swift, Kotlin, Python)
+mark the type's declaration.
+
+**In a test, on the test function — never on the fixture.** A fixture covers whatever its
+tests happen to cover, which no one can check. Each test states what it verifies, so if
+four tests cover one requirement, all four carry the marker.
+
+**At the level that reaches code.** Mark the sub-system or interface requirement the code
+implements. A level with `traced = false` is never marked; `check` rejects it.
+
+**A path containing `test` or `spec`** (configurable as `test_paths`) is a test
+reference; anything else is code.
+
+## Examples
+
+C, on the implementing header:
+
+```c
+/**
+ * @file pwm_py32.h
+ * @brief The PY32F003 implementation of pwm_interface.
+ *
+ * @REQ_REF(TSSR_FWN_023) no code above the abstraction may name a vendor register
+ */
+```
+
+Swift, on the type that implements it:
+
+```swift
+/// Keeps one connection per Master and addresses each independently.
+///
+/// @REQ_REF(TSSR_APP_001) several Masters from one client, none aware of another
+final class MasterConnections { … }
+```
+
+A test, with Given/When/Then — every test function gets this block, marker or not:
+
+```cpp
+/**
+ * @test Each colour reaches the PWM channel the board assigned to it.
+ *
+ * Given an indicator wired to channels 4, 5 and 6 for red, green and blue.
+ * When  a distinct value is set on each element.
+ * Then  each value is written to that element's own channel, and to no other.
+ *
+ * @REQ_REF(TSSR_FWM_006) a discrete RGB indicator under independent PWM per colour
+ */
+TEST_F(IndicatorTest, WritesEachElementToItsOwnChannel)
+```
+
+```swift
+/// @test A Master keeps its name across a reconnect over a different transport.
+///
+/// Given a Master named "Station" over WiFi.
+/// When  it reconnects over USB.
+/// Then  the app shows it as "Station", as one Master.
+///
+/// @REQ_REF(TSSR_APP_002) names key to device identity, not to an address
+func testNameSurvivesTransportChange() { … }
+```
+
+## What `check` enforces
+
+A marker naming several IDs, a marker with no description, a marker on an interface, a
+non-test marker outside `declaration_extensions`, a marker to an undefined requirement,
+and a marker on a level that is never traced directly. Whether the *right* code carries
+the marker is a judgement — make it honestly, and never add a marker to close a gap the
+code does not close.