Review and scope decisions

Resolved stakeholder questions

All decisions below were clarified with the project owner on 2026-10-18. The project owner accepted requirements STV_SHR_001 through STV_SHR_046 as stakeholder baseline v1 on 2026-10-18; see Sources and evidence. Acceptance records agreement to the requirements, not implementation or successful verification.

Resolved - navigation: Explore incoming and outgoing relationships from any displayed object, with separate model-labeled controls for each direction (Navigate relationships in b... (STV_SHR_013), Distinguish incoming and ou... (STV_SHR_035)). Empty types have no controls; isolated nodes show “No related objects” (Indicate objects without re... (STV_SHR_029)).
Resolved - model integration: Reuse the host project’s Sphinx-Needs type and relationship definitions, supplemented by replaceable layout and accepted-status mappings. Additional ordered levels are allowed; invalid required mappings fail the build (Use a replaceable input dat... (STV_SHR_014), Configure accepted-status v... (STV_SHR_032), Reject invalid or incomplet... (STV_SHR_036), Define additional ordered a... (STV_SHR_037), Reuse the host project's mo... (STV_SHR_045)).
Resolved - inspection: Nodes show ID and shortened title. Hover details contain all information displayed by the full Need object, without field selection settings. Long tooltips stay within the window and remain open while hovered, with scrolling. Node activation opens the original object in a new tab (Inspect discovered objects (STV_SHR_008), Inspect object details on h... (STV_SHR_015), Open the original Need obje... (STV_SHR_016), Keep long tooltips readable... (STV_SHR_033)).
Resolved - deployment: Generated documentation works offline from disk and on static hosting without an application server (Explore documentation offline (STV_SHR_017), Explore documentation on st... (STV_SHR_018)).
Resolved - shared objects: One shared node is the default. Independent separate occurrences and mode switching are retained as later-scope features. Switching preserves exploration state; shared mode displays the union of expanded traces (Select how shared objects a... (STV_SHR_019) through Combine expanded traces in ... (STV_SHR_023)).
Resolved - cycles and collapse: Cycles close through a connection or reference without endless repetition. Collapsing a branch retains objects reachable through other open paths (Show cycles without repeati... (STV_SHR_024), Preserve objects reached th... (STV_SHR_025)).
Resolved - invalid starting ID: Explicit unknown/hidden IDs fail the build with an error identifying the invocation (Require a valid starting ID (STV_SHR_026)). The accepted starting-node amendment replaces omitted-ID failure with project entry and supports multiple explicit seeds (Start from the project when... (STV_SHR_047), Select multiple starting ob... (STV_SHR_048)).
Resolved - broken traces: The host build validates and fails broken traces; the extension still renders valid data and marked missing-target placeholders containing the target ID (Render valid traces despite... (STV_SHR_027), Identify unresolved trace t... (STV_SHR_028)).
Resolved - type colors: Reuse host type colors, with a built-in default scheme for omitted colors (Distinguish artifact types ... (STV_SHR_030)).
Resolved - acceptance styling: Red node borders mark states outside the model-defined accepted values, defaulting to accepted. Missing and empty statuses count as not accepted (Mark artifacts that are not... (STV_SHR_031), Configure accepted-status v... (STV_SHR_032)).
Resolved - test placement: Test cases appear to the right of artifacts. A shared test node is to the right of all connected artifacts; later separate occurrences appear beside their respective artifacts (Position test evidence in c... (STV_SHR_012)).
Resolved - interaction scope: Keyboard operation with visible focus, independent views per page, zoom and pan are required initially (Operate the view using the ... (STV_SHR_034), Explore multiple views inde... (STV_SHR_038) through Pan the traceability view (STV_SHR_040)).
Resolved - compatibility: Firefox desktop on Windows; Python 3.10+, Sphinx 8.1.3 and Sphinx-Needs 8.2.0 initially (Support Firefox desktop (STV_SHR_041), Support the initial documen... (STV_SHR_042)).
Resolved - capacity: Projects may contain tens of thousands of Needs. Each view permits at most 200 visible occurrences, including duplicates and placeholders. An expansion or mode switch exceeding the cap leaves the view unchanged with an explanation (Explore a bounded view of a... (STV_SHR_043), Explain expansions blocked ... (STV_SHR_044)).
Resolved - distribution: Deliver a reusable, installable Sphinx extension for use in other documentation projects (Deliver a reusable installa... (STV_SHR_046)).
Resolved - configuration scope: Avoid separate settings for every visual detail; fixed node contents and full-object tooltips need no field-selection configuration. This preserves the explicitly agreed model mappings.

Agreed MVP scope

Start with shared-node mode only. Embed a seeded view in RST, navigate in both directions, preserve model-defined artifact levels, inspect objects and produce self-contained HTML for Firefox on Windows. Reuse host model definitions with additional layout and acceptance mappings. Include type/status styling, independent views, keyboard operation, zoom, pan and the capacity constraints. Deliver the extension as a reusable installable package.

The release_initial and release_later tags record release allocation independently of priority and review status. Requirements involving both modes apply to the shared-node workflow initially; their separate-occurrence and switching clauses apply when the later mode is delivered.

Deferred features - scope resolved

Separate-occurrence mode, its selector, independent occurrence expansion and cross-mode state preservation/combination: later scope (Select how shared objects a... (STV_SHR_019), Preserve exploration when s... (STV_SHR_021), Explore separate occurrence... (STV_SHR_022), Combine expanded traces in ... (STV_SHR_023)). No later release number is assigned.
Touch interaction, including alternatives to hover: deferred beyond the MVP.
Other browsers, Linux and macOS: deferred beyond the MVP.
Other Sphinx and Sphinx-Needs versions: deferred beyond the MVP.
Widget-specific JavaScript behavior inside details: deferred; static rendered content and original-page navigation are sufficient initially (STV_SWR_049).

Owner design clarification queue

The owner requested step-by-step clarification of remaining design decisions. The following historical queue records the owner decisions; later concept review findings are tracked separately in Concept review records:

Resolved: external Needs without local full bodies show available metadata, their original link and “Full details unavailable locally”; no external page download/cache is required. See Inspect external Needs with... (STV_SWR_047) and the explicit MVP clarification in Inspect object details on h... (STV_SHR_015). Hidden Need visibility is resolved separately in item 2.
Resolved: host-hidden Needs and incident relationships are excluded before publication, with no missing-target placeholder revealing the hidden ID; hidden seeds fail with a source-located build error. See Respect host-hidden Need ob... (STV_SWR_048).
Resolved: preserve rendered text, images and non-executable widget markup in MVP details; widget-specific JavaScript remains on the original Need page. See Preserve static third-party... (STV_SWR_049) and the scope clarification in Inspect object details on h... (STV_SHR_015).
Deferred by owner: select the project distribution license later. No license is assigned now. Dependency notices remain part of the packaging design; resolve project licensing before external distribution.
Resolved: measure the first MVP with the planned large-project fixture, then agree response-time and memory budgets from the results. No numeric budgets are assigned now. The hard 200-visible-node limit remains unchanged.

All five queued topics now have an owner decision: items 1, 2, 3 and 5 are resolved; project license selection is explicitly deferred. None remains an unanswered question from that original queue. Concept review subsequently identified remote embedded media as STV_REVIEW_007; the owner-approved fallback and round-2 re-review now resolve it.

Update each item and the affected requirements/ADRs after its answer. Preserve stakeholder baseline v1 history; any changed obligation needs explicit revision evidence rather than silently inheriting its previous acceptance. Implementation checks and deferred occurrence-mode policy are not additional MVP owner decisions unless evidence reveals a scope conflict.

Remaining refinement - not blockers for design

Detailed elicitation is paused at the owner’s request. Resolve these through architecture work, prototype feedback and later requirement refinement:

Resolved in the internal concept: one supplemental Sphinx config mapping; see Internal interfaces and model contract and Implementation concept and handover.
Resolved in the internal concept: full ID and two-line title clamp.
Resolved design behavior: retain external links without fetching/caching their destinations; indicate when a full body is unavailable offline. This is the owner-agreed external-object fallback. Hidden objects and their incident relationships are excluded; no full-body parity is claimed for unavailable external bodies.
Use the planned 30,000-Need/90,000-edge benchmark for first MVP measurements; agree response-time and memory budgets afterward by owner decision.
Later-mode behavior when shared-mode navigation changes saved independent occurrence states.
Additional accessibility criteria beyond the agreed keyboard workflow.

Working assumptions - not confirmed obligations

Exploration is read-only; editing Needs is outside the current draft.
Unrevealed ancestors need not be displayed automatically.

Project maturity and review outcomes are maintained in Project maturity.

Revision history

2026-10-18: Owner agreed to set performance budgets after first MVP measurements, retaining the hard 200-node limit. All queued owner topics are resolved or explicitly deferred.
2026-10-18: Owner deferred project license selection; no license was assigned.
2026-10-18: Owner confirmed static widget content as sufficient for MVP details; clarified STV_SHR_015 and added STV_SWR_049.
2026-10-18: Owner confirmed hidden-object exclusion and hidden-seed rejection; clarified STV_SHR_002 and added STV_SWR_048.
2026-10-18: Owner confirmed external-object fallback as sufficient for MVP; clarified STV_SHR_015 scope, refined STV_SYS_006/STV_SWR_015 and added STV_SWR_047. Baseline v1 acceptance history is retained.
2026-10-18: Completed the concrete dependency and implementation concept, added ADR 004, version/lock artifacts and verification gates, and recorded library bundling and rendered-content extraction evidence.
2026-10-18: Added draft internal requirements, proposed system/software elements, architecture diagrams, interfaces and three proposed ADRs.
2026-10-18: Project owner accepted STV_SHR_001 through STV_SHR_046 as stakeholder requirements baseline v1. All priorities remain unassigned and verification states remain not_assessed.
2026-10-18: Reconciled all clarified topics as resolved, separated deferred scope from remaining refinement, confirmed the shared-node MVP, host-model reuse and reusable extension delivery.
2026-10-18: Extended STV_SHR_044 to blocked mode switches and recorded the owner’s request to pause detailed elicitation in favor of high-level MVP scope.
2026-10-18: Refined STV_SHR_043 to count duplicate occurrences and missing-target placeholders toward the 200-node limit.
2026-10-18: Added STV_SHR_044 for atomic rejection of expansions exceeding the node limit, with an explanatory message.
2026-10-18: Added STV_SHR_043 for projects with tens of thousands of Needs and a maximum of 200 visible nodes per view.
2026-10-18: Added STV_SHR_042 for the agreed initial documentation toolchain.
2026-10-18: Restricted STV_SHR_041’s initial platform scope to Windows and deferred Linux and macOS support.
2026-10-18: Added STV_SHR_041 for Firefox desktop as the sole initial browser target; deferred support for other browsers.
2026-10-18: Added STV_SHR_039 and STV_SHR_040 for initial-release zoom and pan, and extended keyboard-operation coverage to include them.
2026-10-18: Added STV_SHR_038 for multiple independent views per page, explicitly allocated to the initial release.
2026-10-18: Added STV_SHR_037 for extensible model-defined artifact levels and identified the previously specified hierarchy as the default.
2026-10-18: Added STV_SHR_036 for build-time rejection of invalid or incomplete input models, preserving explicitly agreed defaults.
2026-10-18: Refined STV_SHR_012 for test cases linked to multiple artifacts in both display modes.
2026-10-18: Refined STV_SHR_031 to treat missing or empty status values as not accepted.
2026-10-18: Refined STV_SHR_030 to use a built-in default color scheme for artifact types lacking configured colors.
2026-10-18: Refined STV_SHR_030 to reuse host Sphinx-Needs type colors rather than introducing another palette configuration.
2026-10-18: Added STV_SHR_035 for separate model-labeled incoming and outgoing expansion and collapse controls.
2026-10-18: Recorded touch support as a deferred feature beyond the initial release, without assigning a later release.
2026-10-18: Added STV_SHR_034 for keyboard-only operation and visible focus.
2026-10-18: Added STV_SHR_033 for bounded, persistent-on-hover, scrollable tooltips.
2026-10-18: Refined STV_SHR_015 to show all full-object information in the tooltip without configurable field selection; recorded the preference to limit configuration.
2026-10-18: Added STV_SHR_032 and refined STV_SHR_031 for model-defined accepted-status values, defaulting to accepted.
2026-10-18: Added STV_SHR_031 after confirming that status highlighting applies to node borders.
2026-10-18: Refined STV_SHR_008 to fixed ID/title node contents, added STV_SHR_030 for artifact-type backgrounds, and recorded the status-color clarification needed.
2026-10-18: Extended STV_SHR_026 to reject omitted starting IDs as well as unknown IDs.
2026-10-18: Added STV_SHR_029 for nodes without relationships and controls for nonempty relationship types only.
2026-10-18: Added STV_SHR_028 for missing-target placeholders.
2026-10-18: Added STV_SHR_027 to separate host broken-trace validation from extension rendering.
2026-10-18: Added STV_SHR_026 to reject unknown starting IDs at build time.
2026-10-18: Added STV_SHR_025 for retaining objects reached through other open paths when a branch is collapsed.
2026-10-18: Added STV_SHR_024 for finite cycle presentation in both display modes.
2026-10-18: Added STV_SHR_022 and STV_SHR_023 for independent occurrence expansion and the union of expanded traces when switching to shared mode.
2026-10-18: Added STV_SHR_021 to make the expected preservation of expansion state explicit when switching display modes.
2026-10-18: Added STV_SHR_020 for the confirmed shared-node default.
2026-10-18: Added STV_SHR_019 for selecting shared-object presentation in the view itself.
2026-10-18: Added STV_SHR_017 and STV_SHR_018 for offline use and static hosting without an application server.
2026-10-18: Refined STV_SHR_008 to cover node summaries and added STV_SHR_015 and STV_SHR_016 for hover details and opening original objects in new tabs.
2026-10-18: Added STV_SHR_014 for a configurable, replaceable input data model.
2026-10-18: Added STV_SHR_013 for explicitly confirmed bidirectional navigation and resolved the directionality question.
2026-10-18: Initial draft from the project owner’s description. Created stable IDs STV_SHR_001 through STV_SHR_012. All requirements remain drafts; priorities and release allocations remain unassigned.
2026-10-18: Converted the initial Markdown draft into canonical RST Needs, preserving all 12 IDs; added the shared-method documentation structure.

CR_013 nine-category evidence rows

The owner requested the concept/review/implementation sequence and chose a fallback row for ambiguous evidence. STV_CR_013: Vertical target levels for artifacts and test records records the amendment; Round 10: CR_013 classified evidence rows owns review, acceptance and implementation gates.

PR014 boundary marker

The owner requested a visible grey marker at the existing clip edge, analysis and the full V-cycle fix. Mark the visible graph boun... (STV_PR_014) records the plan; Round 11: PR014 visible viewport boundary owns scoped acceptance and PR014 viewport boundary: development verification retains actual execution evidence.

CR014 persistent details decisions

The owner selected per-view reuse/FIFO, persistence through graph changes and an author-configurable limit. STV_CR_014: Persistent artifact details on the right side records the amendment; Round 12: Persistent per-view details owns scoped concept acceptance and implementation feedback. Earlier hover and content obligations remain regression constraints.

PR015 acceptance findings

The owner requested doubled detail width, folded metadata with working arrows and actual artifact navigation from header IDs. Correct detail readability,... (STV_PR_015) and Round 13: Detail acceptance corrections record the scope and technical review. No new stakeholder scope or release authorization is inferred.

v1.0.0 release acceptance

On 2026-10-24 the owner approved PRSA-001 through PRSA-005 and final PR015 presentation. Round 14: Owner acceptance for v1.0.0 records the scoped acceptance; v1.0.0 released authorizes v1.0.0 with runner/hosted work deferred.

CR015-018 concept increment, 2026-10-25

The owner explicitly accepted CR015-018 and STV_SHR_058-061 and requested concept creation. The later save clarification resolves location selection as browser-managed Save As with documented settings. This is not internal concept acceptance. Proposed ADR011, draft STV_SYS_011/STV_SWR_066-072 and nine draft canonical cases supply the scoped handover; Project maturity holds actual checks and current readiness. The font configuration design uses independent author scales, defaults 0.7; export captures only the visible workspace, excluding controls, with activation-time hover semantics in Internal interfaces and model contract.

Retained scope includes Firefox desktop, offline/static hosting, independent views, current seed identities, hidden exclusions, node capacity and persistent card lifecycle. Full graph export, mandatory filesystem pickers, vector-editor portability and new mobile/touch qualification are excluded. Product execution remains separate; Round 15: CR015-018 controls and SVG concept records subsequent delegated concept review/acceptance. Historical accepted reviews and hashes are not rewritten for these new revisions.