Skip to content

Home

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

projectbuddy Wiki

This wiki is the home for projectbuddy's spec-driven design documentation (System Requirements Specification, Software Requirements Specification, Requirements Traceability Matrix, Architecture Packet), per operator direction. It satisfies repo-standards-review's REQ and ARCH gates (VITechnologies/projectbuddy#9, #10).

It is also structured as an Obsidian vault (.obsidian/ config committed alongside these pages) -- clone this wiki repo (git clone https://github.com/VITechnologies/projectbuddy.wiki.git) and open the resulting folder directly in Obsidian for graph/backlink views. Links use standard [[Wiki Link]] double-bracket syntax, which both Obsidian and GitHub's own wiki renderer (Gollum) understand natively (unlike the main repo, where GitHub does not render [[...]] and repo-standards-review's own lychee-based link checker does not support it either -- see each page's own cross-links to the main repo for why ADRs and the compliance stamp stay there instead of here).

Specs

Capability Status

  • Peer-Intelligence: shipped peer diagnostics and model identity, candidate benchmark behavior, and remaining proof gates.
  • REQ-108: candidate source-derived PPL configuration, mandatory bounded local review, and explicit separation from native-build proof.
  • SYS-REQ-029: integrated local Ollama trust boundary; epic #229 links seven implemented contracts and regression evidence through Software-Requirements-Specification. Live desktop/build and stable-release qualification are not implied; unsupported checkpoint custody fails closed.
  • Epic #250: P0 authorization primitives and P1 offline Windows 11 synthetic UI, independent oracle, one-of exact UI action broker, and calibration scorer are integrated (SYS-REQ-031, SYS-REQ-032, PR #254). Issue #253 remains open for reviewed calibration data, frozen thresholds, and live qualification. No live VM/model/capture run is claimed.
  • P2 issue #255 integrates the active-capture MCP consumer and bounded three-mode scheduler in develop through PRs #256 and #258. The Actor resource producer is pinned only as a local candidate; no native Windows live capture/model/action or calibration run is qualified. Issue #257 tracks the Vagrant inspection blocker. The proposed native qualification topology is Planned-Epic-250-Native-Qualification-Design; it does not authorize implementation or production activation.
  • SYS-REQ-034 and REQ-131 through REQ-133 add pre-implementation constraints for interrupted downloads, operator-approved storage reserve, and run-bound loopback ports; verification remains planned.
  • SYS-REQ-035 and REQ-134 now specify a grant-bound VS Code guest console with setup-only keyboard/mouse input and a server-enforced read-only lock before capture. The existing Remmina candidate does not meet the revised requirement; implementation and live qualification remain planned.

Structure

Each spec is split into small linked pages, so the Obsidian graph and backlinks show real relationships and an agent can load one requirement or section at a time:

  • system-requirements/: one page per SYS-REQ-###.
  • software-requirements/: one page per REQ-###, including a retired page for each retired ID.
  • tests/: one page per TEST-###. A stub page marks an ID that is registered in the RTM but has no test-case definition yet.
  • architecture/: one page per Architecture Packet section; a parent section lists its child sections.

The four spec pages above are hubs. Their requirement and test tables, and the Architecture Packet's sections, are invisible-marker indexes of those pages. Each ID page holds one ## <Column> section per table column with the cell text on one line; its title line carries the RTM short title. The standards scan reassembles the hubs into the original single documents and fails closed if any page content would be left out, so keep extra notes off ID and section pages. For whole-table review, signed-in GitHub users can open any scan run summary to see the rebuilt Requirements Traceability Matrix, with each row linked back to its page, and download its assembled-wiki-spec artifact for all four rebuilt documents. Both are generated views; edit these pages, not the views.

Link conventions: write unpiped [[Page-Name]] links (no | alias and no #heading anchor; link the section page instead), and link every ID mention, for example [[REQ-001]]. IDs in code formatting stay unlinked. Pages are capped at 16 KiB (16,384 bytes); split a growing section into child pages. The standards scan enforces these link rules and the page cap, and it fails without staging anything if any page breaks them.

To add a requirement, create the next unused REQ-### page, list it in both the Software Requirements Specification and Requirements Traceability Matrix table indexes, and add its trace links. Never reuse a retired ID.

Process

Spec-first going forward: a new SYS-REQ-### or REQ-### requirement should be added before the corresponding code change is made in the main repo -- not only retroactively documenting what already exists. In practice, every wiki commit to date has been pushed directly to master (confirmed via git log --all: zero branches other than master exist in this wiki's history) -- the branch-then-push-reviewed model this page originally described has not actually been exercised, since this is currently a solo-maintainer workflow with no second reviewer for wiki changes.

Related (lives in the main repo, not this wiki)

  • docs/architecture/adr/ADR-0001-adopt-gitflow-for-release-governance.md
  • docs/architecture/adr/ADR-0002-adopt-ephemeral-container-lunit-release-gate.md (superseded by ADR-0003)
  • docs/architecture/adr/ADR-0003-ephemeral-container-lunit-release-gate-revised.md
  • docs/architecture/standards-compliance.md

Clone this wiki locally