Skip to content

Software Requirements Specification

Jump to bottom
sergio velderrain edited this page Nov 12, 2026 · 54 revisions

Software Requirements Specification

Document Control

  • System: VITechnologies/projectbuddy
  • Version: Living document; existing-behavior baseline last identified as v0.3.29, with separately marked planned changes
  • Owner: svelderrainruiz
  • Status: Active baseline plus explicitly Planned requirements. Planned requirements describe intended future behavior, not a claim that code or live proof already exists. New requirements precede implementation (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 the repo-standards-review REQ gate with Requirements-Traceability-Matrix (VITechnologies/projectbuddy#9) and establishing the baseline for all future spec-first changes.
  • System-level needs and boundaries are specified separately in System-Requirements-Specification; allocation to this SRS is recorded in Requirements-Traceability-Matrix.
  • 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

REQ-039 records the six conditions in the accepted ADR-0006 baseline. REQ-070 through REQ-086 are additional planned conditions selected for the broader lifecycle; they do not amend that accepted ADR. A reviewed successor decision is required before changing the release policy.

Ollama Inference Path

The dedicated epic #229 is allocated from SYS-REQ-029. All seven contracts below are implemented in develop through merged PRs #237 through #243, with exact methods, regression artifacts, platform limits, and CI evidence on their requirement pages. This is not a stable-release or end-to-end live-build qualification:

Requirement Issue Verification reference
REQ-109 approved model identity #230 TEST-111
REQ-110 decision-preserving aggregation #231 TEST-112
REQ-111 context budget and completeness #232 TEST-113
REQ-112 frame attribution and sampled coverage #233 TEST-114
REQ-113 disclosure and retention #234 TEST-115
REQ-114 bounded lifecycle and cancellation #235 TEST-116
REQ-115 private identity-bound resumption #236 TEST-117, TEST-118

Existing issue #217 owns model selection/identity generation, issue #219 owns source-config feature integration, and issues #223/#226 own the initial LBA assisted-benchmark feature. This slice does not reassign those issues, expand MCP/VM authority, permit remote inference, or claim a native build. The cross-adapter acceptance design is TEST-118; executed offline boundary cases and their limits are recorded in SYS-REQ-029. The final integrated Python suite passes 2,142 tests, and the source-config suite passes 91 .NET tests. A bounded CPU-only public synthetic transport smoke passed without private evidence. Checkpoint custody is POSIX-only with fail-closed behavior elsewhere. Supported accounting trusts declared compatible daemon metadata and caller-reviewed template/media limits; samples do not establish continuous coverage, hashes do not authenticate a malicious same-user writer, and client timeouts do not prove server completion. Native builds, real desktop/private evidence, infrastructure changes and stable releases retain separate gates.

The follow-up issue #244 was specified before implementation by REQ-118 / TEST-119 and integrated through PR #245. Its canonical CPU-only/thread policy is verified by actual wire and request-hash tests in both adapters; current full suites pass 2,153 Python and 100 .NET tests. The earlier synthetic transport smoke is not substituted for this proof. A separately authorized metadata-only live invocation completed read-only context/evidence validation but was refused at its client deadline; no successful assessment, benchmark, retry, or native-build result is claimed.

The diagnostic follow-up issue #246 was specified before implementation by REQ-119 / TEST-120 and integrated through PR #247. Current full suites pass 2,166 Python and 108 .NET tests; all seven applicable upstream gates passed. Requested private refusal observations remain distinct from success and do not authorize inference, retries or relaxed deadlines. The one separately authorized metadata-only L2 refused at inference, preserving exit 2, zero retries and unknown server completion; no final receipt or model/native-build acceptance exists. The missing-review administrative merge used explicit scoped operator authority, not independent review. Follow-up issue #248 was specified before implementation as REQ-120 / TEST-121 and integrated through PR #249, merge 69db2c8616f976cdab207a78c715430204697dcb. The current full suites pass 2,171 Python and 108 .NET tests; all seven PR checks passed. Plan-only mode reuses canonical request budgeting but performs no MCP/Ollama call and does not estimate latency or query model metadata. The PR used explicit operator-authorized administrative missing-review bypass, not independent review. No additional live attempt, inference, or native build was performed.

Live Agent Session Authorization

Approved epic #250 extends stopped-capture assessment with agent-initiated, periodic, and continuous frame/event use while capture remains active. Its P0 policy boundary is specified by SYS-REQ-030 / REQ-121 / REQ-122 / TEST-122 / TEST-123 and tracked in issue #251. A one-use provision permit must authorize exactly one VM request; only after the provisioner result and independent inventory prove one new UUID may the runner seal exact MCP calls and teardown authority to that UUID. P0 policy/broker primitives REQ-121 / REQ-122 are implemented through PR #252, merge fd998aab3551f3ed5665bf809ebc3f08f79209de; full suites pass 2,193 Python and 108 .NET tests and all seven PR checks passed. The offline implementation does not invoke a provisioner or run MCP/Ollama. Capture-time coordinator, synthetic workload/oracle, performance baseline and thresholds, and live VM workflow remain unimplemented and unqualified. Model output cannot create or widen grants, and LBA plan-only command text remains inert. The epic excludes SBOM and native Windows PPL work.

P1 #253 offline UI/oracle and one-of exact-action route merged in PR #254 (61d6e6dd); 2,231 tests, 97% coverage, and all seven checks passed. No live VM/model/capture, host-model calibration, or thresholds are claimed. SBOM and native Windows PPL remain excluded.

P2 #255 depends on Actor #45 for active-capture reads. The read-only consumer, bounded three-mode scheduler, and sealed one-of-two action route are integrated in develop through PRs #256 and #258 (SYS-REQ-033 / REQ-126 / REQ-127 / TEST-127 / TEST-128), but the Actor pin remains local-candidate-only. REQ-128 / REQ-129 / REQ-130 specify the proposed native Windows staging, relay, and drained-trial evidence; REQ-131 / REQ-132 / REQ-133 add resumable artifact, storage-reserve, and per-run port preflight. SYS-REQ-034 allocates these native infrastructure constraints. No native Windows capture/model/action run or reviewed calibration dataset is qualified; issue #257 tracks the Vagrant inspection blocker. ProjectBuddy must not crawl Actor storage.

Baseline Authoring Corrections

REQ-116 separates the evidence-record secret obligation from REQ-093, and REQ-117 separates unprivileged workload execution from REQ-107. These are singular-statement authoring corrections, not Ollama feature scope, new execution authority, reduced safeguards, or newly verified behavior. Their original TEST-095 and TEST-109 links and SYS-REQ-027 allocation are preserved.

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.
  • Existing-behavior claims retain their stated verification basis; rows marked Planned are future targets and are not implemented or live-proven merely by appearing here. Any requirement without a real automated test is identified accordingly. Verification evidence points at the reproducible mechanism or a durable proof, never treating a historical workflow run ID alone as proof of current behavior.

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. REQ-001 lists every disclosed exception; anything not on that list is a violation.
  • 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.
  • Lane workload: a consumer-declared command, with its candidate commit, inputs, outputs, working directory, timeout, toolchain contract, and secret names, that the engine runs in a lane without interpreting (REQ-090).
  • Toolchain contract: the consumer-declared list of tools, each with a probe argument vector, an extraction pattern, and an exact expected version, that a lane must match before the workload starts (REQ-091).
  • Evidence record: the one projectbuddy/lane-evidence@1 record per lane run that binds the candidate, the declaration, the lane, the observed toolchain, and the output digests; it is unsigned and does not by itself authenticate the evidence (REQ-092).
  • Requester: the non-human identity (an agent session, a bot, or a scheduled workflow) that submits a request for a privileged action; it is never an eligible reviewer (REQ-096).
  • Reviewer: a human GitHub user or team listed as a required reviewer of an approval environment; one reviewer's approval or rejection decides a request (SYS-REQ-028).
  • Approval environment: a GitHub Actions environment, one per action class, whose required reviewers gate each request and whose secrets are the only credentials that can perform it (REQ-098). The gate is enforcing when the requester cannot act directly and advisory otherwise (REQ-096).
  • Action class: a named kind of privileged action from a closed list, such as a wiki publish or a release-promotion merge, with its own target pattern, approval environment, and credential (REQ-094).

Clone this wiki locally