Skip to content

Software Requirements Specification

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

Software Requirements Specification

Document Control

  • System: VITechnologies/projectbuddy
  • Version: Initial draft, grounded in the codebase as of v0.3.10
  • Owner: svelderrainruiz
  • Status: Draft -- 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. Keeps the public engine reusable by any fork without leaking one fork's private state. grep for hardcoded project names/identifiers across vm/, root scripts, and workflows returns no matches outside documentation/examples. Manual code review (this SRS's own authoring pass); no automated check yet.
REQ-002 Every VM identity value (VM_NAME, BASEFOLDER, GUEST_FULLNAME, GUEST_HOSTNAME, ISO paths, etc.) 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. 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.
REQ-004 Enable-RepoIssueTracking.ps1 shall only ever enable Issues on a repository, never disable it or touch any other repository setting. A one-directional, safe-by-construction operation 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. Live-verified: New-HumanEscalation.ps1/Enable-RepoIssueTracking.ps1 smoke tests this session (see commit history, 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. Lets an agent re-confirm a blocker is still unresolved without accumulating duplicate issues. 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. Live-verified this session: svelderrainruiz/projectbuddy#18 (create, then update-in-place with title preserved, body replaced, 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 SBOM pipeline scripts (Run-Pipeline.ps1/.sh, 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. Documented in README.md's "Native SBOM reporting" section; no automated regression test yet.
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).
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. Code review of Test-SbomArtifact.ps1's own docstring (Exit codes: 0 ... 1 ... 2 ... 3 ...); exercised informally across this engine's own CI history.
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, never tagged directly off ad-hoc commits to main. Live-verified: v0.3.9/v0.3.10 were both cut through the full release/* flow (see docs/release/release-procedure.md and each release's own PR history).
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. Live-verified this session: standards-compliance-recheck.yml run 42196529270 correctly parsed and compared the stamp.
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.

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 (see Architecture-Packet's Correspondence And Rationale section for the wiring question still open at ci_integration=not_yet_sure).
  • Requirements here describe existing, verified behavior as of v0.3.10; any requirement without a real automated test is explicitly marked "no automated check yet" rather than overstated.

Constraints

  • New requirements added here going forward must be reviewed (branch-then-push in this wiki repo) before the corresponding code change is merged -- spec-first, per operator direction.
  • 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.

Clone this wiki locally