Repository navigation
Software Requirements Specification
sergio velderrain edited this page Nov 6, 2026
·
55 revisions
- 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.
- 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. | 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. |
-
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(see Architecture-Packet's Correspondence And Rationale section for the wiring question still open atci_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.
- 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), matchingrepo-standards-review'srequirements_quality_check.pyrule.