Repository navigation
Software Requirements Specification
sergio velderrain edited this page Nov 7, 2026
·
55 revisions
- 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.
- 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.
| 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 |
| 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). |
-
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 thandocs/requirements/srs.md. The CI-integration question (howrepo-standards-review's scanner, which expects a plain checkout, sees wiki-hosted content) was resolved betweenv0.3.10andv0.3.13(commitc3a36ae, "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.
- 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), matchingrepo-standards-review'srequirements_quality_check.pyrule.
-
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'ssrs-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 passlychee's link checker, which is why this content lives in the wiki rather thandocs/(see Architecture-Packet's Correspondence And Rationale).
-
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 ofREQ-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-reviewcompliance gate (CM/coverage/REQ/ARCH/DOC), which is a different, unrelated use of the same word.