Skip to content

Software Requirements Specification

sergio velderrain edited this page Nov 7, 2026 · 55 revisions

Software Requirements Specification

Document Control

  • System: VITechnologies/projectbuddy
  • Version: Living document, re-synced after every semantic-audit round; current as of v0.3.29
  • Owner: svelderrainruiz
  • Status: Active -- retroactively documents real, existing behavior; new requirements should be added here before implementing new behavior going forward (spec-first), per operator direction.

Scope

  • Purpose: Capture, as governed REQ-### requirements, the behaviors this engine already guarantees today (verified against real code, not invented), satisfying Requirements-Traceability-Matrix (VITechnologies/projectbuddy#9) and establishing the baseline for all future spec-first changes.
  • In scope: VM provisioning scripts, native/container SBOM pipeline scripts, the human-escalation tooling, the repo-onboarding tooling, and this engine's own consumption/versioning model.
  • Out of scope: the specific LabVIEW/VIPM toolchain's own behavior (treated as an external dependency, see Architecture-Packet's Context View), and any downstream consumer's own project-specific configuration.

Stakeholders

Role Need Priority
Product (operator/fork owner) A provisioning/reporting engine that never assumes a specific fork's identity or infrastructure High
Engineering (agent/contributor) Requirements and traceability precise enough to know whether a change is a bug or a deliberate design choice High
QA A way to verify a specific guarantee (e.g. "never auto-updates a pin") without re-reading all the code Medium
Operations (consumer repo maintainer) Predictable upgrade/consumption behavior; no silent floating-version drift High

Requirements

ID Requirement Rationale Fit Criterion Verification
REQ-001 The engine shall ship with zero pre-committed project-specific configuration, identifiers, or credentials, except in scripts explicitly disclosed as narrow-purpose, consumer-vendored reference templates for one specific known consumer (e.g. docker/windows-sbom/Build-LvlibpCandidate.ps1, and provision-ubuntu-vm.yml's package-build phase template -- both already documented as such in the Architecture Packet's Component View and VITechnologies/projectbuddy#62). Keeps the public engine reusable by any fork without leaking one fork's private state, while acknowledging that a small number of intentionally narrow, disclosed reference scripts legitimately need a concrete example to be useful at all. grep for hardcoded project names/identifiers across vm/, root scripts, and workflows returns no matches outside documentation/examples and the disclosed narrow-purpose exceptions above. Verified (manual), as of this round's remediation: the real violations tracked in VITechnologies/projectbuddy#68 (Register-WslRunnerKeepAlive.ps1's default shortcut name, base-bootstrap.sh/provision-guest.sh's hardcoded paths and guest-property name, 11 files' sandbox-sbom-reporting/* schema-namespace strings, unattended-template.xml's 4 <Description> fields, pipeline-config.schema.json's self-referential field docs, and Run-WindowsSbom.ps1/Run-LinuxSbom.ps1's false "VIT Super Network Streams is the default" doc claim) have all been genericized -- confirmed via a repo-wide grep sweep finding zero remaining matches outside the 2 disclosed exceptions and legitimate illustrative-example comments/doc-comments (which cite a real consumer as an example, never as a default/enforced value).
REQ-002 Every VM identity value (VM_NAME, BASEFOLDER, GUEST_FULLNAME, GUEST_HOSTNAME) shall be a required input with no built-in default. Prevents one fork's provisioning run from silently reusing another fork's naming/infrastructure. Each such parameter in vm/windows-labview/*.ps1/*.sh is declared mandatory, with no default value assigned. A few non-identity parameters (e.g. the ISO path, guest username, WinRM port) do have generic, non-fork-specific defaults -- these are deliberately excluded from this guarantee's scope. Manual code review of vm/windows-labview/build-virtualbox.ps1/.sh; no automated check yet.
REQ-003 Downstream repositories consuming this engine shall bump their pinned tag/commit SHA only as a deliberate, reviewed code change -- never automatically, and never by tracking a floating branch or latest. Matches README.md's documented "Upgrade path"; avoids unreviewed behavior changes reaching a consumer silently. README's Consumption model section explicitly states this; no workflow in this engine auto-bumps a consumer's pin. Manual code review; documented in README.md's "Consumption model" section. Scope caveat: this requirement describes this engine's own guarantee (it never auto-bumps anyone) and cannot itself enforce or verify what a given consumer actually does with that guarantee (ISO/IEC/IEEE 29148 S5.2.5 Appropriate/Verifiable) -- e.g. the real SandboxSBOMReporting consumer pins one of its two PROJECTBUDDY_*_REF variables to an untagged commit SHA (labeled by a descriptive comment) rather than a release tag, which is still a deliberate, reviewed pin (satisfying this requirement's actual wording) but not the tagged-release pin a reader might assume "Upgrade path" implies.
REQ-004 Enable-RepoIssueTracking.ps1 shall only ever enable Issues on a repository, never disable it, and shall idempotently seed exactly one companion label as its one other explicitly-disclosed side effect. A one-directional, safe-by-construction operation (plus one narrow, intentional, documented label-seeding step) reduces the blast radius of an accidental/malicious invocation. Script contains no code path that calls gh repo edit with --enable-issues=false or any flag other than --enable-issues; the label-create call uses --force (genuinely idempotent, not "ignore the already-exists error") and a non-zero exit from it is a real, surfaced failure, never silently swallowed. Live-verified this round: ran against the real VITechnologies/projectbuddy repo (already-enabled Issues, idempotent label create/update both confirmed via real gh output), plus New-HumanEscalation.ps1/Enable-RepoIssueTracking.ps1 smoke tests from an earlier session (svelderrainruiz/projectbuddy#20).
REQ-005 New-HumanEscalation.ps1 shall be idempotent for a given -EscalationId: re-invoking it against the same repo and ID updates the existing open issue in place rather than creating a duplicate, verifying the match against the real issue body client-side (not trusting GitHub's search index alone), and surfacing (not silently swallowing) a search failure. Lets an agent re-confirm a blocker is still unresolved without accumulating duplicate issues, and without a flaky/eventually-consistent search silently producing a false match or a hidden duplicate. A second invocation with the same -Repo/-EscalationId but different -Context results in exactly one open issue, with the updated body and the original title preserved; a search failure emits a visible warning rather than silently falling through. Live-verified this round: real create (VITechnologies/projectbuddy#83) then real update-in-place with the same -EscalationId (same issue number, body content genuinely changed, confirmed via gh issue view), test issue closed after. Builds on an earlier session's svelderrainruiz/projectbuddy#18 verification (title preserved, assignee added).
REQ-006 add-project.yml shall reject a project registration whose pipelineConfig does not satisfy pipeline-config.schema.json, before writing anything to PROJECTS_OVERRIDE. Prevents a malformed config from silently corrupting the shared repository variable other projects also depend on. A registration attempt with an invalid config exits non-zero and leaves PROJECTS_OVERRIDE unchanged. Code review of add-project.yml's pwsh -Command "... Test-Json ..." validation step, which runs before any variable_command("set", ...) call.
REQ-007 Native and containerized SBOM pipeline scripts (Run-Pipeline.ps1, Run-WindowsSbom.ps1, Run-LinuxSbom.ps1) shall fail closed (no default) if DEPENDENCY_TRACK_URL is required for the requested reporting mode but not supplied. Prevents a fork without a configured Dependency-Track server from silently attempting to reach someone else's private instance. Running in full reporting mode with DEPENDENCY_TRACK_URL unset produces a clear error and no network call to any default host. Run-Pipeline.ps1's Test-DependencyTrackReadiness throws on a missing absolute HTTPS URL; both containerized pipelines fail closed in-container the same way. Run-Pipeline.sh is excluded from this requirement's scope -- it is a separate, unrelated LabVIEWCLI analysis tool with no Dependency-Track handling at all, not a native SBOM pipeline script.
REQ-008 Test-ToolchainPresence.ps1 shall have no side effects: it never installs, downloads, or modifies anything, only reports what is already present on PATH. Lets a downstream workflow safely smoke-test that this engine's scripts are consumable without any risk of mutating the runner. Script contains no Install-*, Invoke-WebRequest, New-Item, or similar mutating calls; only Get-Command. Code review of scripts/Test-ToolchainPresence.ps1's own docstring and body (it exists specifically to prove this), plus real CI dispatch: ci-assurance.yml's toolchain-smoke-test job now calls this engine's own toolchain-smoke-test.yml reusable workflow against itself on every push/PR (previously documented as never actually invoked anywhere in this repo).
REQ-009 Test-SbomArtifact.ps1 shall distinguish, via distinct exit codes, between artifact/build integrity failure (1), vulnerability-policy failure (2), and reporting failure (3), so a caller never mistakes one failure class for another. A CI consumer needs to react differently (e.g. block a release vs. just warn) depending on which guarantee failed. Each of the three failure classes is reachable via a real fixture and produces its own distinct, documented exit code. Real, assertion-based Pester fixture tests: scripts/tests/Test-SbomArtifact.Tests.ps1 constructs a minimal fixture per failure class (and the success path) and asserts the exact resulting ExitCode/Outcome, run in CI by ci-assurance.yml's pester-tests job on every push/PR.
REQ-010 This repository's branch governance shall follow GitFlow (develop, feature/*, release/*, hotfix/*), per ADR-0001. Required to satisfy repo-standards-review's CM gate, per operator decision (VITechnologies/projectbuddy#6). A develop branch exists alongside main; releases are cut via release/vX.Y.Z branches merged to both main and develop (or confirmed as a legitimate no-op merge-back if the two are already content-identical), never tagged directly off ad-hoc commits to main. Live-verified: v0.3.9-v0.3.27 were all cut through the full release/* flow (see docs/release/release-procedure.md and each release's own PR history). v0.3.28 has one disclosed, judged exception (a non-release PR landed directly on main after its release branch's own promotion, to ship a real-CI-dispatch-discovered parse-error fix without cutting a second release branch for one two-line change) -- recorded in docs/cm/cm-plan.md's Status Accounting section, not a silent deviation.
REQ-011 Every compliance claim this repository makes against repo-standards-review shall be stamped with the exact version (tag and commit SHA) of that standard it was assessed against. An undated compliance claim degrades silently as the standard evolves, with no way to tell which version it was ever actually checked against. docs/architecture/standards-compliance.md carries a machine-parseable tag=... sha=... marker. Reproducible via standards-compliance-recheck.yml's "Compare Stamped Version Against Latest" step, which parses and compares the stamp fresh on every run (not a one-time historical check).
REQ-012 The automated re-certification check shall never silently update the compliance stamp on drift. Automation overwriting the stamp on drift risks asserting compliance that was never actually re-verified by a human. standards-compliance-recheck.yml only ever opens/updates a tracking issue on drift; it has no code path that writes to docs/architecture/standards-compliance.md. Code review of standards-compliance-recheck.yml's "Flag Re-certification Due" step, which only calls New-HumanEscalation.ps1.
REQ-013 build-virtualbox.ps1/.sh (both the Windows- and Ubuntu-LabVIEW families) shall reject a create-vm/provision-public request whose base-OS ISO does not match a pinned SHA-256 hash, before attaching that media to any VM. Prevents an operator-supplied or cached installer file from silently differing from the exact, previously-verified binary the pipeline was proven against. build-virtualbox.sh's -Run/--run path (both families) pipes the downloaded/supplied ISO through sha256sum --check against the pinned iso_sha256, exiting non-zero on mismatch, before VM creation. Scoped to the base-OS ISO specifically -- the optional, operator-overridable auxiliary bootstrap media (-NsisBootstrapIso/NSIS_BOOTSTRAP_ISO, SERVICE_BOOTSTRAP_ISO) is only existence-checked, not hash-verified, a known, narrower gap tracked separately. Code review of vm/windows-labview/build-virtualbox.sh (the actually-invoked script per provision-windows-labview-vm.yml:130,132 -- its sibling vm/windows-labview/build-virtualbox.ps1 has equivalent Get-FileHash/Stop-Build logic but is never called by any real workflow, confirmed via a repo-wide reference search) and vm/ubuntu-labview/build-virtualbox.sh (the sha256sum --check call ahead of VM creation). This is distinct from provision-windows-labview-vm.yml's separate install-vipm/install-labview phases, which pin the VIPM/LabVIEW installer's own hash, not the base-OS ISO.
REQ-014 A VM shutdown initiated by the provisioning pipeline shall attempt a graceful WinRM-driven shutdown first, fall back to an ACPI power button signal only if that does not complete within budget, and fall back to a hard poweroff only if ACPI also does not complete within budget -- never skipping directly to a hard poweroff. acpipowerbutton alone has been observed live to leave WinRM responsive while the guest OS never actually reaches poweroff; a hard poweroff first would risk corrupting in-flight guest state unnecessarily when a graceful path is available. provision-windows-labview-vm.yml's "Attach Installer Media And Restart" step's shutdown branch is coded in exactly this order (WinRM shutdown -> poll -> ACPI -> poll -> hard poweroff), each guarded by its own timeout loop. Code review of the step's own inline comments describing this as an intentional reliability finding, not an arbitrary implementation choice.
REQ-015 After restarting a Windows LabVIEW guest, the pipeline shall confirm WinRM readiness via a real WinRM round-trip request, not merely a successful TCP connection to the WinRM port. A bare TCP-port check was observed live to report ready while the SOAP/PowerShell-remoting service was not yet actually able to handle requests, causing a ReadTimeoutError on the very next real command. provision-windows-labview-vm.yml's "Attach Installer Media And Restart" step polls provision-windows-guest.py ... wait-ready (a real WinRM call) in a retry loop, and explicitly fails the step (rather than silently exhausting retries and reporting success) if readiness is never reached. Code review; the step's own inline comment documents the earlier, more confusing failure mode this specifically replaced.
REQ-016 Guest/service-account credential files written to a runner's temp directory during provisioning shall be created with mode 0600. Limits the blast radius of a credential file if the runner's temp directory is otherwise readable. install -m 0600 /dev/null "$WINRM_PASSWORD_FILE" (or equivalent) precedes every write of a guest password/PAT to a temp file across provision-windows-labview-vm.yml. Code review of every credential-file-writing step in provision-windows-labview-vm.yml.
REQ-017 A credential file written during provisioning shall not be left behind after the step that uses it completes. Avoids leaking a secret into retained CI artifacts/logs beyond the single step that legitimately needs it. Every step in provision-windows-labview-vm.yml that writes the guest/WinRM password file or the runner-registration PAT file shreds it (falling back to rm -f) before the step ends: the create-vm, install-vipm, install-labview, "Attach Installer Media And Restart", and register-runner steps all clean up the guest/WinRM password file they wrote, and register-runner additionally cleans up its PAT file. Code review of every GUEST_PASSWORD_FILE/WINRM_PASSWORD_FILE/PAT_FILE write site in provision-windows-labview-vm.yml and its matching shred (with a rm -f fallback) cleanup line.
REQ-018 LabVIEW product activation shall remain an exclusively human-driven, interactive step -- never an automated phase of VM provisioning -- wherever such an activation step genuinely exists in this engine's supported platforms. Activation is the one step in the pipeline deliberately kept outside automation, per operator decision, rather than an oversight or a not-yet-implemented phase. A human must retain direct, interactive control over this specific action rather than it being delegated to any script or service account. This is scoped to LabVIEW specifically -- see REQ-032 for VIPM activation, which is a deliberately-automated exception with its own narrower requirement. Real workflow_dispatch proof (#62, run 42394542555) found this engine's own Ubuntu-LabVIEW appliance genuinely has no separate LabVIEW license-activation step at all (NI's Linux LabVIEW distribution's authenticated package-repository access is itself the licensing gate) -- complete-activation.sh's former usage-text claim that the operator "has already activated LabVIEW Professional in the guest" was an unverified assumption carried over from the Windows family, not a real precondition, and has been corrected in the script itself. This requirement's own prohibition is satisfied vacuously for Linux (there is no human-only LabVIEW activation step to protect from automation there) and remains fully, genuinely in force for Windows, where a real interactive activation step does exist. (Merged from the former REQ-019, retired 2026-11-07: its own Fit Criterion read "Same evidence as REQ-018," failing ISO/IEC/IEEE 29148 §5.2.5's "Necessary" characteristic -- its removal leaves no capability deficiency not already covered by this row. See the Notation section's ID-retirement convention.) provision-windows-labview-vm.yml's own header comment states this explicitly ("LabVIEW/VIPM activation remains an operator-driven interactive step and is intentionally NOT a phase here -- it is the one step that must stay human"); no phase option in that workflow's workflow_dispatch input performs activation -- genuinely true for Windows, confirmed real since no script anywhere in this repo performs LabVIEW activation for either platform. For Ubuntu/Linux, real workflow_dispatch proof (run 42394542555) confirms complete-activation succeeds end-to-end with zero human-interactive LabVIEW steps of any kind -- only REQ-032's automated VIPM activation runs. Real workflow_dispatch dispatch of provision-ubuntu-vm.yml's complete-activation phase against a disposable appliance (#62), producing a genuine activation-receipt.json with outcome: PASS and a functional LabVIEW known-answer probe (20+22=42) -- not merely code review of usage text, which this requirement's prior verification wrongly relied on alone. Windows's own human-activation step remains verified by code review only (no real interactive activation has been live-dispatch-proven this session).
REQ-020 vm-fleet-status.yml shall independently re-derive each tracked VM's real-world state (actual GitHub Actions runner registration + actual VirtualBox power state) rather than reporting runner-inventory.json's own self-logged status as ground truth. A locally-logged "success" was observed live to not guarantee the real-world outcome matched: a register-runner run reported success while the runner had actually registered under the wrong name, a discrepancy only caught by directly querying the GitHub API. vm-fleet-status.yml's own header comment documents this exact incident as the reason for the design; each matrix job queries gh api .../actions/runners and VirtualBox state directly, not runner-inventory.json's status field. Code review of vm-fleet-status.yml's header comment and its per-VM matrix job steps.
REQ-021 The Ubuntu-LabVIEW provisioning workflow shall support running its own orchestration from either a Linux or a Windows self-hosted provisioner host, with behaviorally equivalent Linux (build-virtualbox.sh) and Windows (build-virtualbox.ps1) adapter scripts taking the same identity parameters (VmName/VM_NAME, BaseFolder/BASEFOLDER, SshHostPort/SSH_HOST_PORT, GuestFullName/GUEST_FULLNAME, GuestHostname/GUEST_HOSTNAME). Parity is at the adapter-script/parameter level specifically, not phase-by-phase: 6 of provision-ubuntu-vm.yml's 10 real phases (inspect-public, console-fingerprint, repair-ssh-console, restart-public, repair-public, resume-public) are deliberately one-OS-only per .github/scripts/validate-vm-provisioning-dispatch.py's own WINDOWS_ONLY_PHASES/LINUX_ONLY_PHASES sets. The host that happens to be available to run the orchestrator should not constrain which guest OS family can be provisioned, for the phases both hosts are expected to run. provision-ubuntu-vm.yml's runs-on is computed from the runner_os dispatch input (linux or windows); its "Validate Linux Adapter Plan"/"Validate Windows Adapter Plan" steps are mutually exclusive on runner.os and invoke the two adapter scripts with the same parameter set. Code review of provision-ubuntu-vm.yml's dual adapter-plan validation steps and validate-vm-provisioning-dispatch.py's phase/OS sets.
REQ-022 full Dependency-Track reporting mode shall fail the entire pipeline run before any project's checkout starts if DEPENDENCY_TRACK_URL is not an absolute HTTPS URL or does not answer a real preflight request. Avoids wasting a full checkout/build/scan cycle only to fail at the final publish step for a misconfigured or unreachable reporting backend. Test-DependencyTrackReadiness performs a live GET .../api/openapi.json request and throws before Run-Pipeline.ps1's per-project loop begins if that request fails or returns no API paths. Code review of Build-Sbom.ps1's Test-DependencyTrackReadiness/Resolve-DependencyTrackPolicy functions.
REQ-023 full Dependency-Track reporting mode shall refuse to disable the Critical/High security gate. A reporting mode whose entire purpose is enforcing a vulnerability policy should not be configurable into silently not enforcing it. Resolve-DependencyTrackPolicy throws if $Mode -eq "full" and $SecurityGate -eq "0". Code review of Build-Sbom.ps1's Resolve-DependencyTrackPolicy function.
REQ-024 The native pipeline's policy gate shall fail a project if Dependency-Track's returned metrics are not confirmed fresh relative to the BOM import just uploaded. Prevents a stale or unrelated prior metrics snapshot from being mistaken for a clean result on a newly-uploaded SBOM. Test-PipelinePolicyGate compares Metrics.lastOccurrence against a required-occurrence marker tied to the actual upload, rejecting metrics whose lastOccurrence is not strictly newer -- a timestamp-monotonicity freshness check, not a cryptographic or upload-token binding to the literal uploaded BOM bytes. Code review of internal/Pipeline.Stages.ps1's Test-PipelinePolicyGate function and its caller in Publish-DependencyTrack.
REQ-025 The native pipeline shall record which of policy/reporting/build category a run failure belongs to, based on whether any stage recorded a failed gate, else whether the dependencyTrack stage was still running, else treating the failure as a build-category failure. Lets Test-SbomArtifact.ps1 return a distinct exit code per failure class, so a CI consumer can react differently (block a release vs. just warn) without re-parsing log text. Complete-PipelineRunRecord sets failureCategory to policy if any stage shows gate: failed, else reporting if the dependencyTrack stage was still running, else build. Code review of Build-Sbom.ps1's Complete-PipelineRunRecord function; cross-checked against Test-SbomArtifact.ps1's own documented exit codes (REQ-009).
REQ-026 The native pipeline's optional secondary source-checkout stage shall reject a checkoutPath that escapes the project's own checkout root. Prevents a maliciously or accidentally misconfigured sourceCheckouts entry from writing outside the intended project directory. Invoke-PipelineSourceCheckoutStage rejects a rooted path, a path containing .. segments, a path traversing a symlink/reparse-point ancestor, or a path that already exists at the resolved destination -- throwing in each case rather than silently normalizing or overwriting. Code review of internal/Pipeline.Stages.ps1's Invoke-PipelineSourceCheckoutStage function.
REQ-027 A pre-built .lvlibp release dependency fetched by the native pipeline shall only be accepted from a published, immutable (non-draft) GitHub Release whose in-toto attestation, resolved tag commit, and downloaded release manifest all cross-match the requested repository, tag, version, and asset. A floating, unverified binary dependency would undermine every other supply-chain guarantee this pipeline makes elsewhere (checkout pinning, SBOM generation, vulnerability gating). Invoke-LvlibpReleaseDependencyStage throws on any mismatch across: release immutability/draft status, gh release verify's attestation statement type/repository/tag/purl, the annotated-tag-chain-resolved commit SHA, the release manifest's own module/source/release fields, and a required exactly-one-match for each asset (including its SBOM) with SHA-256 verification after download. Code review of internal/Pipeline.Stages.ps1's Invoke-LvlibpReleaseDependencyStage function (lines ~373-620).
REQ-028 The native pipeline shall not apply Grype's own scan findings as a pass/fail gate. Dependency-Track's own metrics are this pipeline's deliberate, single security gate; Grype's native-pipeline role is reporting only, avoiding two independent and potentially conflicting gates for the same SBOM. Invoke-PipelineScanStage records the Grype stage's gate as not-gated explicitly, with an inline comment stating Dependency-Track metrics are the real gate. Code review of internal/Pipeline.Stages.ps1's Invoke-PipelineScanStage function.
REQ-029 Both containerized SBOM pipelines (Linux and Windows) shall apply Grype's own findings as a real, configurable severity-threshold gate. A container run without a Dependency-Track backend configured still needs an independent vulnerability gate; this is a deliberate behavioral difference from the native pipeline (REQ-028), not an inconsistency. GRYPE_FAIL_ON (default high) is read and enforced by both linux_sbom_pipeline.py and windows_sbom_pipeline.ps1, each documented in their own module docstring. Code review of both container pipelines' own environment-variable documentation and gate-enforcement code.
REQ-030 add-project.yml shall upsert exactly one entry per project name in PROJECTS_OVERRIDE, replacing an existing entry with the same name rather than appending a duplicate, even if more than one pre-existing entry already shares that name. Prevents a re-registration of an already-known project from accumulating duplicate, conflicting entries in the shared repository variable other projects also depend on. A registration attempt for a project name that already has one or more entries in PROJECTS_OVERRIDE results in PROJECTS_OVERRIDE containing exactly one entry for that name afterward, with its fields replaced by the new attempt's values. Code review of add-project.yml's upsert step: every existing entry matching name is filtered out before the fresh entry is appended, so the result always has exactly one entry for that name regardless of how many pre-existing duplicates there were.
REQ-031 add-project.yml's best-effort Issues-enablement step for repositories referenced by a newly registered project shall never cause the registration itself to fail, even if ACTIONS_REPO_ADMIN_TOKEN is unset or a referenced repo's Issues-enable call fails. A registration's primary purpose (upserting PROJECTS_OVERRIDE/VIPM_TOML_CONFIGS) must not be blocked by an unrelated, lower-priority convenience side effect. The "Enable Issue Tracking on Referenced Repos" step runs only after the upsert step has already completed and recorded success; a missing token or a per-repo failure inside it only emits a ::warning::, never a workflow failure. Code review of .github/workflows/add-project.yml's "Enable Issue Tracking on Referenced Repos" step (conditioned on the upsert step's own output; every per-repo call is followed by a warning-only fallback, never exit 1).
REQ-032 VIPM activation on the Ubuntu-LabVIEW family shall be performed non-interactively via vipm activate --direct-vipm-io, as part of the complete-activation phase's guest-side call chain, and is the only activation this phase performs or needs. VIPM ships a documented, safe non-interactive activation flag that LabVIEW itself does not have an equivalent for; automating VIPM's activation specifically reduces operator burden without touching the human-only guarantee REQ-018 makes for LabVIEW, wherever such a human-only LabVIEW step genuinely exists. Real workflow_dispatch proof (#62, run 42394542555) confirms the Ubuntu-LabVIEW family has no separate LabVIEW-already-activated precondition to satisfy at all -- the former "documented operator convention" language was an unverified carry-over assumption from the Windows family, now corrected in complete-activation.sh's own usage text. The real call chain's lack of a LabVIEW-activation-state check was not a gap; there is no such state to check. vm/ubuntu-labview/activate-vipm.sh runs VIPM_NONINTERACTIVE=1 vipm activate --direct-vipm-io --serial-number ... --name ... --email ... with no interactive prompt. It is invoked by vm/ubuntu-labview/capture-activation.sh (not directly by complete-activation.sh, which copies both scripts onto the guest and then invokes capture-activation.sh), unconditionally whenever a VIPM env file is supplied -- before capture-activation.sh's own LabVIEW-file-existence checks. A genuine activation-receipt.json (outcome: PASS) confirms VIPM reports a perpetual, Professional, validly-activated state and LabVIEW itself runs a real known-answer probe successfully with no LabVIEW-specific activation step ever having run. Real workflow_dispatch dispatch of provision-ubuntu-vm.yml's complete-activation phase (#62, run 42394542555) against a disposable appliance, producing a genuine receipt with vipm.validThrough: "Perpetual", vipm.validActivationCode: true, and a passing LabVIEW known-answer probe -- not merely code review of the call chain, which this requirement's prior verification wrongly relied on alone.
REQ-033 This engine's release process shall require, for the exact commit being released, a passing JUnit report from both the Windows and Linux ephemeral LabVIEW-container gates (REQ-034/REQ-036) before that release ships, per ADR-0003. A pre-implementation 3-model consensus review of the original ADR-0002 draft found this requirement conflated "a container gate exists" with "both platforms are proven to work"; a second round-2 review of the ADR-0003 revision then found "pinned-commit" itself was ambiguous between two different repositories' commits. Corrected here: "the exact commit being released" always means this engine's own release-candidate commit (the one the gate's workflow_dispatch run is triggered against); the separate, external ni/labview-icon-editor suite commit REQ-034/REQ-036 pin is a distinct identifier, recorded alongside it, never substituted for it. A release is not published unless a workflow_dispatch run triggered against that exact release-candidate commit SHA, for both platforms, each produces a JUnit report satisfying REQ-034's/REQ-036's full acceptance criteria (suite identity, integrity, waiver limits, and no-VIPM conditions, not merely a non-skipped-test-count floor). Does not retroactively gate v0.3.31 or earlier. Takes effect only once both ADR-0003 phases have succeeded and that success is reflected by promoting this row's own Status from Planned to Active -- a historical passing run on an unrelated commit, or an unmerged spike branch, does not activate this requirement. Active (promoted from Planned 2026-11-07): both ADR-0003 phases have succeeded with real workflow_dispatch proof on both the fork and upstream VITechnologies/projectbuddy -- Phase 1/Windows (#91, fork run 42368671863, upstream run 42369960284) and Phase 2/Linux (#92, fork run 42372457595, upstream run 42372700928). This row's own promotion condition is now met; see ADR-0003's Phase-2 Addendum. Tracked in #87.
REQ-034 Windows LUnit execution shall run a specific, pinned ni/labview-icon-editor commit's LUnit suite, unattended, inside a fresh GitHub-hosted-runner Windows LabVIEW container, with no VIPM installation, activation, or secret present anywhere in the container's build or runtime. Per ADR-0003: ni/labview-icon-editor#575 is a reference design to adapt (open/unmerged, not yet green end-to-end), not proof this engine's own implementation already works -- Phase 1 requires a real green run in this engine's own CI. GitHub-hosted runners are #575's own reference choice and avoid reintroducing the self-hosted long-lived-infrastructure risk this session's VBoxSVC finding demonstrated; this is a hosting-risk argument, not a claim the mechanism is already proven (round-2 review correction). A fresh container build from this engine's pinned-by-digest nationalinstruments/labview Windows image, given SHA-256-verified LUnit/LUnit CLI VI package files, runs the pinned-commit suite unattended and produces a lunit.xml JUnit report covering every test case in that pinned suite, with zero failures and zero errors, with the single, narrow exception of the upstream-known Test Write Read Library Icon Data.vi tag-mismatch waiver if still unresolved upstream at implementation time (re-approved at every suite-pin update or it lapses; no other test's failure may be waived without a new ADR) -- and with no VIPM installation, activation call, secret, or credential present anywhere in the container's build or runtime. Implementation-level detail (exact CLI invocation, port, package versions) belongs in #87's design notes, not this statement. Verified (live, fork + upstream): implemented and live-dispatch-proven via real workflow_dispatch runs on both the fork (#91, run 42368671863) and upstream VITechnologies/projectbuddy (run 42369960284) -- identical result: 10 total tests, 1 named waiver (Test Write Read Library Icon Data.vi), vipmPresence: false. Re-verified after #94's review fixed a missing-engineCommit/report-completeness/commit-validation gap shared with REQ-036 (#97): a fresh upstream run (42375129680) reproduces the same result, now also recording engineCommit. Tracked in #87.
REQ-035 A disposable Linux LUnit feasibility spike shall determine, before Linux becomes release-gating, whether the LUnit/LUnit CLI VI packages and LabVIEWCLI's LUnit operation can run unattended (including any headless-display/Xvfb requirement) against this engine's pinned-by-digest nationalinstruments/labview Linux container image on a GitHub-hosted Linux runner. No upstream reference implementation exists for Linux; per ADR-0003, this engine must independently determine feasibility rather than assume Windows's mechanism transfers unchanged. Resolved: outcome (a), feasible (per ADR-0003's Phase-2 Addendum) -- confirmed via direct local Docker testing (Linux containers run natively on this engine's own build host) before CI: LabVIEWCLI's LUnit operation runs to completion with no externally-provided DISPLAY/Xvfb setup needed -- LabVIEW itself spawns its own internal Xvfb :99 virtual framebuffer when none is provided, confirmed via a direct process-tree inspection (#94's independent verification review, which corrected this row's earlier "no virtual framebuffer at all" overclaim). No NSIS-equivalent installer is needed (neither of the two Windows-container-specific bugs that required one apply to Linux). Two additional Linux-specific named test failures were found and confirmed (see REQ-036), beyond the Windows-shared waiver. Verified (live, fork + upstream): confirmed feasible via direct local Docker testing, then real workflow_dispatch runs on both the fork (run 42372457595) and upstream VITechnologies/projectbuddy (run 42372700928, after #92 merged) -- identical results. See ADR-0003's Phase-2 Addendum.
REQ-036 Linux LUnit execution shall run the pinned-commit ni/labview-icon-editor suite, unattended, inside a fresh GitHub-hosted-runner Linux LabVIEW container, with no VIPM installation, activation, or secret present anywhere in the container's build or runtime. Keeps both platforms on one architecture (no-VIPM, pinned-commit, GitHub-hosted, SHA-256-verified, digest-pinned) now that REQ-035 has confirmed feasibility, satisfying REQ-033's dual-platform gate without inventing a second, inconsistent design. Fully self-contained (round-2 review finding, now resolved with real evidence): this row states its own complete, Linux-specific waiver list rather than cross-referencing REQ-034's Windows-only one. The two Linux-specific waivers are formally authorized by ADR-0004 (per ADR-0003's own rule that waiving a test beyond the single Windows exception requires a new ADR, not a quiet SRS edit -- a process gap #94's review found and ADR-0004 closed), each with its own follow-up issue (#95, #96) and pin-update expiry condition. A fresh container build from this engine's pinned-by-digest nationalinstruments/labview Linux image, given the same SHA-256-verified LUnit/LUnit CLI VI package files (deployed by a plain file copy, not an NSIS installer -- confirmed unnecessary for Linux), runs the pinned-commit suite unattended and produces a lunit.xml JUnit report covering every one of the pinned suite's 10 test cases (a truncated/partial run, or any skipped test case, blocks the gate regardless of waiver status), with zero failures and zero errors, with exactly three named, lapsing waivers and no others: Test Write Read Library Icon Data.vi (shared with REQ-034, the same upstream tag-mismatch), Test Window Position.vi (Linux-specific, #95: 7 of 8 window-bounds assertions fail by a consistent 1-pixel rendering offset versus the test's Windows-captured expected values), and Test INI Settings.vi (Linux-specific, #96: both of its 2 assertions expect Windows-only default font names -- "Small Fonts", "Calibri" -- that Linux LabVIEW's real default, "LabVIEW Application", does not match) -- and with no VIPM installation, activation call, secret, or credential present anywhere in the container's build or runtime, and with this engine's own release-candidate commit recorded in every gate result alongside the suite commit (REQ-033). Verified (live, fork + upstream): confirmed via direct local Docker testing, then real workflow_dispatch runs on both the fork (run 42372457595) and upstream (run 42372700928, after #92 merged) -- identical results: 10 total tests, all 3 named waivers, vipmPresence: false. An independent 3-model post-implementation verification review (#94) then found and this engine fixed: a Linux VIPM-detection gap (wrong marker paths), a report-completeness gap (a truncated/skipped run could have passed), a missing formal waiver ADR (ADR-0004), and several documentation overclaims (this row's own Xvfb wording, a wrong installMethod manifest value), per #97. A fresh upstream re-verification run after the fix (42375127600) reproduces the same result, now also recording engineCommit and with the corrected installMethod. Tracked in #87.
REQ-037 This engine shall provide a dedicated, versioned, read-only decoding tool for labview-benchmark-actor VS Code extension capture output (schema labview-benchmark-actor/launch-capture@1), for agent/operator LabVIEW-VM troubleshooting use -- diagnostic tooling only, never a CI gate or release-blocking check. A real capture this session (run-1794072448721) showed genuine troubleshooting signal (a one-time disk-read burst at launch, sustained but unexplained CPU activity) reachable only by ad-hoc, repeated raw-JSON parsing -- including a real wrong assumption about resources.disk's shape, corrected only by finding the richer top-level frames[] array instead. The extension's own MCP viewer tools (lbaBenchmarkSummary/lbaBenchmarkPanel) show fixed demo data regardless of new captures and cannot substitute for this. Per ADR-0005, corrected by that ADR's own Addendum after inspecting the extension's real source: dhashHex/screen being null is the normal, structurally-expected output of the live "Capture LabVIEW Launch" command (it never computes a perceptual hash or emits screen dimensions), not an anomaly. A capture directory (an explicit path, or the most recently created run-<timestamp> one under the extension's globalStorage/captures/ root) is decoded into a structured summary covering duration, frame count, per-resource (CPU/RAM/disk, per-disk-name) min/max/avg, peak I/O event(s) with frame index, dualPacket integrity result, and explicit flags for the source-verified anomaly conditions ADR-0005's Addendum names (capture-status.json state of failed/capturing rather than stopped; dualPacket.outcome other than authoritative; a per-frame dhashHex population inconsistent across frames within one capture) -- with a visible warning, not a silent misparse, if capture.json's/capture-status.json's own schema field does not match the tag(s) this engine has pinned. Does not attempt automatic visual/image classification of the PNG frames in v1 -- only narrows down which frame indices are worth a manual look. Active (promoted from Planned 2026-11-07): scripts/Decode-LbaCapture.py implemented per #102, 23 synthetic-fixture pytest unit tests (99% line coverage on the module, 68/68 total in scripts/tests/ passing) plus a real verification run against the genuine run-1794072448721 capture -- correctly reproduces the peak-write finding (31.724 MB/s on nvme0n1 at frame index 432) and, consistent with the ADR-0005 Addendum correction, reports zero false anomalies for this healthy capture (neither its uniformly-null dhashHex nor its null screen field is flagged).
REQ-038 The Ubuntu-LabVIEW VM family shall support a register-runner provisioning phase achieving functional parity with the Windows family's own register-runner phase (vm/windows-labview/provision-windows-guest.py + Register-WindowsRunner.ps1): registers a provisioned VM as a GitHub Actions self-hosted runner over SSH (no interactive console session required), using a dedicated, non-privileged local service account for the runner's systemd service, and -- per REQ-020's own established discipline, after a real past incident where a Windows register-runner self-reported success while the runner had actually registered under the wrong name -- independently cross-checks the real GitHub API afterward rather than trusting the registration command's own exit code alone. Before this session, Ubuntu had no runner-registration automation at all (only the Windows family did), which blocked treating "VM creation succeeds" as a symmetric, equally-meaningful release precondition across both platforms (the operator's stated expectation driving this requirement). Building genuine parity first, rather than silently settling for an asymmetric/weaker Ubuntu milestone, was a deliberate operator decision. A fresh or already-provisioned Ubuntu-LabVIEW VM, given a runner-registration PAT, a target repository, a runner name, labels, and a dedicated service-account name, ends with: a running systemd service for the registered runner; a real gh api repos/<target>/actions/runners entry for that exact name with status: "online" and all expected labels (self-hosted, Linux, X64, plus the supplied custom labels); and the supplied PAT file shredded (not merely deleted) from the guest before the phase ends, matching REQ-017's existing credential-cleanup discipline. Pending live verification (dispatch in progress at authoring time, VITechnologies/projectbuddy run tracked in #105/the implementation PR) -- promotes to Verified (live) once a real workflow_dispatch of provision-ubuntu-vm.yml's register-runner phase against a genuine VM produces a runner independently confirmed online via gh api (not just the phase's own exit code).

Assumptions

  • repo-standards-review's own templates (srs-template.md, rtm-template.csv, architecture-packet-template.md) define the expected shape of this document, the RTM, and the architecture packet; this SRS follows that shape even though it is authored in the wiki rather than docs/requirements/srs.md. The CI-integration question (how repo-standards-review's scanner, which expects a plain checkout, sees wiki-hosted content) was resolved between v0.3.10 and v0.3.13 (commit c3a36ae, "Wire REQ/ARCH CI verification") -- see Architecture-Packet's Correspondence And Rationale section for how.
  • Requirements here describe existing, verified behavior as of v0.3.29; any requirement without a real automated test is explicitly marked "no automated check yet" rather than overstated. Verification evidence points at the reproducible mechanism (the actual code path or a re-runnable workflow), never at one specific historical workflow run ID -- a run ID is ephemeral and does not, by itself, prove anything about the current state of the code.

Constraints

  • New requirements added here going forward must be added before the corresponding code change is merged -- spec-first, per operator direction. (The "reviewed, via a local branch" model originally intended for this wiki has not actually been exercised in practice -- every commit to date has been pushed directly to master, a solo-maintainer-workflow reality disclosed on the wiki's own Home page.)
  • Each REQ-### row must contain at most one "shall" (singular-requirement discipline, ISO/IEC/IEEE 29148 §5.2.5), matching repo-standards-review's requirements_quality_check.py rule.

Notation

  • REQ-### identifiers are stable and never renumbered/reused once assigned, even if a requirement is later merged into another or removed; a removed requirement's ID is documented as removed, not silently deleted and reused.
  • Each requirement row is: Statement ("shall") | Rationale | Fit Criterion | Verification, per repo-standards-review's srs-template.md.
  • [[Double-bracket links]] are native Obsidian/GitHub-wiki syntax resolving to another page in this same wiki (e.g. Architecture-Packet); they do not render on GitHub's main-repo markdown viewer or pass lychee's link checker, which is why this content lives in the wiki rather than docs/ (see Architecture-Packet's Correspondence And Rationale).

Glossary

  • Engine: this repository (VITechnologies/projectbuddy), as distinct from any consumer repository that uses it.
  • Consumer / consuming repository: a separate repository (e.g. VITechnologies/SandboxSBOMReporting) that pins and invokes this engine's reusable workflows/scripts, supplying its own real, private project configuration.
  • Fork: a GitHub fork of this engine used for day-to-day active development (svelderrainruiz/projectbuddy), distinct from "consumer" above -- a fork develops the engine itself; a consumer only uses it.
  • Disclosed narrow-purpose exception: a script intentionally hardcoding one specific known consumer's identifiers, explicitly documented as such (e.g. docker/windows-sbom/Build-LvlibpCandidate.ps1), carved out of REQ-001's general zero-identifiers guarantee rather than treated as a bug.
  • Fit Criterion: the ISO/IEC/IEEE 29148 term for an objective, checkable test of whether a requirement is actually met.
  • Gate: a pass/fail checkpoint in the SBOM pipeline (e.g. the Dependency-Track policy gate, the Grype severity gate) -- distinct from a repo-standards-review compliance gate (CM/coverage/REQ/ARCH/DOC), which is a different, unrelated use of the same word.

Clone this wiki locally