reqmd Software Requirements

The parser package shall use goldmark to walk the Markdown AST, extracting requirement ID from headings and YAML attributes from fenced ```attr ``` blocks. The first heading+attr pair encountered determines the requirement level (reqLevel); headings at reqLevel with an adjacent attr block are top-level requirements, and headings at reqLevel+1 with an adjacent attr block are sub-requirements (ParentID set to the active parent). Non-attr headings are body text. The parser SHALL also extract YAML frontmatter from .md files, with first-file-wins merge semantics across files in the same document directory. Parsing shall run in parallel across files via a worker pool sized to runtime.NumCPU().

The schema package shall compile schema.yaml via github.com/google/jsonschema-go (JSON Schema 2020-12), inject six built-in attribute definitions (trace, version, root, leaf, disposition, disposition-reason) before validation, and provide property introspection via direct map[string]any access. The parent-child hierarchy is structural (from parser heading detection), not schema-driven — no built-in attribute is needed.

The graph package shall build a pure Go in-memory directed graph from all parsed requirements via three sub-passes: Pass 1 creates CachedNode structs with typed fields (ReqID, Root, Leaf, IsChild, Disposition, External, IDPrefix, Inbound/Outbound slices); Pass 2 builds adjacency from manual trace attributes; Pass 3 builds parent-child edges from the parser-set ParentID field. Broken parent references in Pass 3 produce ERROR-level results. No external graph database is used at runtime.

The graph package shall implement ten Pass 2 trace checks: broken reference (WARNING), circular (ERROR), untraced (WARNING — suppressed for sub-requirements via !node.IsChild), no-downstream (WARNING), disposition without reason (WARNING), mandatory disposition (ERROR), ID prefix mismatch (ERROR), ID prefix collision (ERROR), duplicate ID (ERROR), and ambiguous reference (ERROR). ERROR-level results produce exit code 1; WARNING and INFO do not. Broken parent references from Pass 3 also produce ERROR-level results collected into the same report.

The exporter package shall produce three output formats: CSV (attribute columns with bufio.Writer streaming), HTML (standalone page with card-based layout, goldmark-rendered body and rationale, upstream/downstream trace columns, doc-level trace chain tab strip, search-and-filter toolbar, persistent 240px fixed left sidebar tree TOC with collapsible parent nodes and scroll-spy highlighting, nested sub-requirement cards inside their parent, mobile hamburger toggle, and theme toggle), and graph (persistent graph database in ladybugdb format for external Cypher query tools).

The HTML export SHALL render requirement body and rationale through goldmark to support inline Markdown syntax (code spans, emphasis, emoji, math, fenced code blocks) rather than plain text escaping.

The cmd package shall use cobra to dispatch subcommands and coordinate the full pipeline: parse documents, compile schemas, validate attributes, build the graph, run trace checks, and format the report to stdout with the appropriate exit code.

The parser package shall surface discovery errors (unreadable directories, malformed schema.yaml, unparseable .md) as ParseError entries in the report rather than aborting the run, so that a single bad file does not mask the rest of the tree. Discover walks the tree, locates every directory containing a schema.yaml, and parses all .md files in that directory in parallel; per-file failures are collected and reported with file context.

The check command shall accept a --relaxed-versions flag that demotes version-pin findings with direction: "outdated" (upstream newer than the pin) from ERROR to WARNING. Predated findings (pin ahead of upstream) remain ERROR regardless of the flag, since they indicate a downstream referencing a version that does not exist on the upstream.

The graph package's New constructor shall build the in-memory directed graph from parsed requirements without performing I/O or side effects, so that graph construction is deterministic and cannot fail at runtime. Node creation, trace-edge building, and parent-child edge building run as three ordered sub-passes over the already-parsed in-memory document set.

The exporter's ExportWithTraces shall resolve cross-document trace links via a TraceResolver that maps requirement IDs to output-relative HTML paths, so that rendered HTML contains only safe relative links (no absolute filesystem paths, no unescaped user-controlled content in href attributes). Link targets that do not resolve to a known requirement are omitted rather than emitted as broken anchors.

The serve subcommand shall watch a requirements directory tree and serve a live-reloading HTML preview over HTTP. On any .md or schema.yaml change (create, write, remove, or rename) detected via fsnotify — or via polling fallback when fsnotify is unavailable — it re-parses, rebuilds the trace graph, re-checks graph-level invariants, re-exports all documents, and pushes a reload event to connected browsers via Server-Sent Events. serve runs graph-level checks (trace refs, cycles, coverage) but does not re-run JSON Schema validation; the status line reports graph-check counts, not per-requirement validity.

The serve subcommand shall accept a repeatable --results <path> flag that loads ephemeral verification results (CTRF JSON or manual-results markdown) via the same pipeline as check --results. When results are loaded, verdict badges (pass/fail/skipped/inconclusive) are rendered on measure cards in the HTML output, and the failing-verdict and missing-verdict graph checks run on every rebuild. Result file paths (directories and individual .ctrf.json/.json files) shall also be watched for changes — alongside spec files — so that editing a CTRF JSON or manual-results markdown triggers an immediate rebuild and browser refresh.

The baseline diff <tag1> <tag2> subcommand shall compare requirement specifications between two git tags without a working-tree checkout, by extracting the repository at each tag via git archive | tar, parsing both versions with the standard pipeline, and producing a semantic diff of requirements (added, removed, modified with attribute-level detail) and schemas (new/removed properties, changed required fields). It shall also report added, removed, and updated git submodules via git ls-tree. Output is colored text by default with --json for structured output.

The internal/verify package shall parse CTRF JSON reports (top-level results.tests[]) and map each test to a measure ID via the tests[].extra.x-reqmd.id field. CTRF status shall map to reqmd outcome as: passed→pass, failed→fail, skipped→skipped, pending|other→inconclusive, and any status with flaky: true→inconclusive. Tests with no x-reqmd.id shall be skipped with a WARNING. The ~N version pin in the measure ID shall be preserved.

The internal/verify package shall load manual-results markdown directories via parser.Discover, extracting outcome, verifier, evidence, verified-at, and trace from each requirement's attr block. Manual-results dirs live outside the spec root and carry their own user-supplied schema.yaml.

The internal/verify package shall merge all loaded results by measure ID (stripping ~N pins from the key), keeping the latest verdict per measure by CTRF tests[].stop (ms-epoch) or manual verified-at. Each merged result shall be synthesized as a pseudo-requirement with ID RESULT:<measure-id>, trace: [MEASURE-ID~N] (pin preserved for version-pin checks), outcome: <verdict>, and status: approved, then appended to the document slice before graph.New.

The graph shall run two new checks when result pseudo-requirements are present: missing-verdict (WARNING — an approved verification measure, identified by a non-empty verify attribute, has no result tracing to it; draft measures are skipped) and failing-verdict (ERROR — a measure's latest result has outcome fail). Both checks are no-ops when no result nodes exist. Both are suppressible via reqmd-suppress.