
# ISO/IEC/IEEE 29148 alignment (fulfillment + deviations)

This document describes how the `spec` system fulfills ISO/IEC/IEEE 29148:2018 requirements engineering guidance, using the templates + included examples as the source of truth, plus the current project practices. Where relevant, it also calls out deviations, non-goals, and potential improvements.

**Assumptions about the project (process controls & standards):**
- **Governance & stakeholders**: stakeholder needs are managed by a steering committee with vote/veto mechanics. The committee defines strategic direction and creates **tasks** that scope individual PRD/DESIGN/ADR documents. Stakeholder identification and needs analysis happen at the **project/task level**, not within individual module specs. Gear specs focus on **actors** (users, systems) that interact with the module, not organizational stakeholders.
- **Repo model**: open-source, single modular mono-repo focused on **shared libraries**; downstream client systems handle final build/deployment/operations elsewhere.
- **Gear integration**: all modules integrate via Rust native calls with automatically generated gRPC/REST API transport; integration patterns are standardized project-wide.
- **Global guidelines**: project-wide standards live in the repository's foundational docs (the architecture manifest and `guidelines/`):
  - Runtime, OS, CPU architecture compatibility (docs/ARCHITECTURE_MANIFEST.md)
  - Security policies and threat models (guidelines/SECURITY.md)
  - Performance/observability guidance (docs/ARCHITECTURE_MANIFEST.md § 12)
  - Architecture patterns and tech stack (docs/ARCHITECTURE_MANIFEST.md)
  - Testing strategy: 90%+ code coverage via unit/integration/e2e/security/performance tests
- **Lifecycle management**: all modules committed to git are maintained; project-wide breaking changes policy (semver), deprecation (6-month notice), and support windows are enforced; gear-level deviations are exceptional.
- **Git/PR record**: all changes flow through PRs with review, discussion, and an immutable merge/audit trail.
- **CI gates**: merges are gated by deterministic checks (lint/build/test) plus deterministic Cypilot ID validation (uniqueness + reference integrity), with additional heuristic review/tooling as needed.
- **Cross-validation**: PRD <-> DESIGN <-> ADR <-> FEATURE <-> code <-> tests are expected to reference shared `cpt-...` IDs where applicable.
- **Documentation approach**: gear-level specs (PRD/DESIGN) document only **deviations** from or **extensions** to global guidelines; avoid duplicating project-wide standards.

## Stakeholders Needs

**Fulfillment:** Stakeholder needs are managed at the **project/task level** by the steering committee, which creates scoped tasks that drive PRD/DESIGN/ADR creation. This aligns with 29148's stakeholder requirements definition while avoiding duplication across module specs. Gear PRDs focus on **actors** (users, systems interacting with the module) rather than organizational stakeholders, which is appropriate for a modular library mono-repo where strategic direction is set centrally. Governance (steering committee vote/veto) is documented in README § Governance & Process. **Library mono-repo disclaimer**: stakeholder needs are primarily about library consumers/maintainers and are captured at the project/root level.

**Deviations / possible future improvements:** add explicit task-to-gear-spec traceability (e.g., task ID references in module PRD frontmatter) and require stakeholder concern mapping for major architectural decisions in root-level ADRs.

## System requirements

**Fulfillment:** The PRD's functional and non-functional requirement sections provide system-level requirement statements with mandatory language, IDs, rationales, source, and actor linkage, aligning with 29148's well-formed requirement guidance. Foundational docs (docs/ARCHITECTURE_MANIFEST.md, guidelines/) establish project-wide baselines, and module PRDs document deviations/extensions, which effectively partitions requirements by scope. Verification methods are implicit (90% test coverage standard) unless exceptional. The layered approach (global + gear-specific) is stronger than per-gear duplication and aligns with modular mono-repo reality.

**Deviations / possible future improvements:** enforce CI checks that every gear requirement explicitly declares if it's a deviation/extension of a global requirement, and add explicit system→module allocation tracing.

## Functional requirements

**Fulfillment:** Functional requirements are clearly structured with MUST language, IDs, rationale, source, and actor mapping, and are traceable into design and feature specs. This is stronger than typical 29148 usage because it embeds traceability and implementation status inline. Verification method is implicit (default: automated tests with 90% coverage) and only documented explicitly for exceptions (analysis, inspection, demonstration), which is pragmatic and reduces documentation overhead without sacrificing ISO alignment.

**Deviations / possible future improvements:** add CI enforcement that every implemented requirement has corresponding test coverage with Cypilot ID references, and require explicit verification method documentation for any requirement not covered by automated tests.

## Non-Functional Requirements

**Fulfillment:** The layered NFR approach (global baselines in the foundational docs — architecture manifest + guidelines/ — plus gear-specific deviations/extensions) aligns well with 29148's quality attribute requirements and is stronger than per-gear duplication. Gear PRDs include explicit NFR categories with measurable thresholds, source, rationale, and architecture allocation (via DESIGN.md NFR Allocation table). Verification methods are implicit (automated benchmarks, security scans, monitoring) unless exceptional. The approach is pragmatic and ISO-aligned for a modular library mono-repo.

**Deviations / possible future improvements:** add CI enforcement that module NFRs explicitly reference which global baseline they deviate from (if any), and require quantitative evidence (benchmark results, scan reports) for all critical NFRs before merge.

## Use Cases

**Fulfillment:** The PRD use case template covers actor, pre/postconditions, main/alternate flows, which satisfies ISO’s scenario-based requirement support. While PRD use cases are optional, `FEATURE.md` provides a stronger behavioral spec layer via Actor Flows (with success/error scenarios and step-by-step interactions, including explicit API/DB touchpoints), which in practice can serve as the project’s “use case realization.”

**Deviations / possible future improvements:** require at least one PRD use case per externally-facing capability and enforce bidirectional links (use case ↔ requirements ↔ feature flow IDs) in PR review/CI.

## Interfaces

**Fulfillment:** The PRD § Public Library Interfaces and DESIGN § External Interfaces & Protocols sections explicitly document module API surfaces, stability guarantees, and integration contracts, aligned to 29148. Standardized module integration (Rust native calls + auto-generated gRPC/REST transport) reduces per-gear interface documentation burden—module specs focus on deviations or unique contracts. Feature flows reference API/DB touchpoints with Cypilot IDs, enabling traceability. **Library mono-repo disclaimer**: integration patterns are project-wide; modules document only their specific public API and external dependencies.

**Deviations / possible future improvements:** add CI validation that all public APIs have corresponding interface documentation with stability guarantees, and enforce breaking-change detection via automated API compatibility checks.

## Architecture Definition

**Fulfillment:** The DESIGN template includes architectural vision, drivers, layers, components, deployment topology, and traceability to requirements, which matches 29148’s allocation of requirements to architecture and design. The architecture is described in a pragmatic, software-first way.

**Deviations / possible future improvements:** it doesn’t force explicit requirement allocation matrices or stakeholder concerns mapping to architecture views. Add a required allocation matrix (requirements → components) and explicit stakeholder concern mapping for each architecture view, and enforce via CI that every requirement has a design allocation.

## Design Viewpoints/Views

**Fulfillment:** `DESIGN.md` explicitly calls out IEEE 42010 view types (context/functional/information/deployment) and provides concrete places to document them (domain model, component model, sequences, deployment topology).

**Deviations / possible future improvements:** what’s missing is formal viewpoint definitions (stakeholders/concerns/model kinds) and correspondence rules (how views stay consistent). Add a short “Viewpoint Definitions” subsection and require at least one correspondence rule (e.g., “every API endpoint in flows must exist in API contracts”).

## Architecture Decisions

**Fulfillment:** The ADR template is robust and ISO-aligned: decision context, drivers, options, consequences, and confirmation are all present, with stable IDs and status. This exceeds typical 29148 practice by making decisions traceable and reviewable as first-class artifacts.

**Deviations / possible future improvements:** the only gap is guidance for linking decisions to specific requirements in a structured way beyond ID references. Add a required “Decides For Requirements” field that references the exact requirement IDs influenced by the ADR, and enforce via PR checks.

## Traceability

**Fulfillment:** The Cypilot ID system and mandated traceability sections in every template provide systematic, bidirectional links across requirements, design, decisions, and features. This is stronger than 29148’s baseline because it operationalizes traceability in human-readable Markdown with optional validation tooling. A formal trace matrix is not required, but the ID system effectively provides the same capability.

**Deviations / possible future improvements:** provide a minimal trace matrix template or tooling output that enumerates links and highlights gaps, and fail CI if references are missing.

## Verification/Validation

**Fulfillment:** Acceptance criteria in PRD/Feature docs plus ADR confirmation provide explicit V&V hooks; the examples show concrete confirmation strategies (unit/integration/manual) and explicit requirement links. **Library mono-repo disclaimer**: end-to-end validation of a deployed system is generally owned by downstream clients; this repo can validate library behavior (unit/integration/property tests), API stability, and documented contracts.

**Deviations / possible future improvements:** verification method and evidence are not required fields for every requirement. Require a per-requirement verification method + evidence link, and have CI enforce that tests reference the relevant `cpt-...` IDs for implemented requirements.

## Lifecycle Coverage

**Fulfillment:** Project-wide lifecycle policies (semver, breaking changes with 6-month deprecation notice, support windows, migration tooling) are documented in the project's foundational docs and enforced across all modules committed to git. Gear PRDs document only lifecycle deviations (exceptional cases). This approach covers library lifecycle (release, upgrade/migration, deprecation, maintenance) appropriate for a shared-library mono-repo. **Library mono-repo disclaimer**: "operations" happen in client deployments; this repo focuses on library lifecycle and API stability.

**Deviations / possible future improvements:** add CI enforcement that breaking changes are flagged and require ADR + migration guide, and maintain a project-wide lifecycle roadmap linking module releases to compatibility/deprecation timelines.

## Change Management

**Fulfillment:** Change control is strong for an open-source mono-repo: Git PRs provide review/audit trails, ADRs have explicit status and dates, and Cypilot IDs make changes traceable across artifacts; governance vote/veto further strengthens control for high-impact changes. **Library mono-repo disclaimer**: changes must prioritize API stability and downstream integration impact.

**Deviations / possible future improvements:** the main gap (vs ISO in regulated contexts) is explicit baselining/versioning language for requirements and a standard impact analysis artifact. Add a lightweight “Baselines & Releases” section (baseline tag + date + scope) and require PR impact analysis including “breaking change / migration / downstream risk”.

## Operational Concept & Environment

**Fulfillment:** Project-wide operational environment (supported runtime, OS, CPU architectures, toolchain versions, compatibility targets) is documented in docs/ARCHITECTURE_MANIFEST.md, aligning with 29148's foundational context requirements. Standardized module integration patterns (Rust native + auto-generated gRPC/REST transport) establish consistent usage modes. Gear PRDs document only environment-specific constraints or deviations. This layered approach is appropriate for a library mono-repo. **Library mono-repo disclaimer**: final deployment environments are owned by downstream clients; this repo specifies library compatibility and integration constraints.

**Deviations / possible future improvements:** add CI validation that gear-specific environment constraints are compatible with project-wide baselines, and maintain a compatibility matrix linking supported environments to tested module combinations.

## Constraints & Assumptions

**Fulfillment:** PRD includes assumptions and risks, and DESIGN includes constraints, so the content is present but spread across documents without explicit requirement linkage. ISO expects constraints to be captured as requirements or design constraints and traced to impacted elements.

**Deviations / possible future improvements:** require constraints to be written as verifiable requirements with IDs and link them to affected design elements, verified by CI on merges.

## Requirement Language & Quality

**Fulfillment:** `PRD.md` explicitly defines requirement language rules (MUST/SHALL only; avoid SHOULD/MAY; avoid fluff/duplication), and the templates push toward verifiable statements.

**Deviations / possible future improvements:** the remaining gap is enforcement: there’s no built-in per-requirement quality checklist and no required verification-method field. Add a short “Requirement Quality Checklist” and require a “Verification Method” line for each requirement (then enforce via PR/CI).

## Requirement Attributes & Allocation

**Fulfillment:** You already have partial attributes and allocation mechanisms spread across templates: PRD requirements include rationale + actors; `DESIGN.md` has “Architecture Drivers” tables mapping requirements to design responses; `FEATURE.md` has “Implements” and “Touches (API/DB/Entities)” which is an explicit allocation-to-implementation hook.

**Deviations / possible future improvements:** what’s missing is a consistent, required attribute schema across all requirements (source, verification method, allocation target). Standardize a small attribute block and enforce completeness + allocation links in CI.

## Open-Source Mono-Repo Practices

**Fulfillment:** A single modular mono-repo with PR-based review and Cypilot IDs supports strong traceability and change control, aligning with ISO’s configuration and verification expectations.

**Deviations / possible future improvements:** the gap is that these practices are not explicitly documented as part of the requirements system, so ISO alignment depends on team discipline rather than required artifacts. Add a brief section that declares PR-based review, mono-repo modular boundaries, and Cypilot-based cross-validation as required process controls.

## CI-Based Cross-Validation

**Fulfillment:** Assuming CI tools are in place, automated checks can enforce 29148-style traceability and verification readiness in an open-source workflow.

**Deviations / possible future improvements:** the missing piece is an explicit, documented CI policy that defines what must pass for requirements, design, code, and tests to be considered aligned. Add a required CI policy section listing the specific checks and linking them to requirements. Example CI responsibilities:
1. **Cypilot validation**: ensure all referenced IDs exist, no duplicates, and cross-doc links are consistent.
2. **Traceability checks**: verify every PRD requirement maps to DESIGN and FEATURE entries.
3. **Requirement quality gates**: enforce MUST/SHALL language, required attributes, and verification methods.
4. **Test linkage**: require tests to reference requirement IDs and fail if missing.
5. **Docs-code sync**: ensure changed code has corresponding spec updates when relevant.
6. **Review policies**: require PR approvals with checklist items for requirement/design/test coverage.

---

## Summary: ISO 29148 fulfillment & gaps

| ISO 29148 Section | Key Fulfillment |
|-------------------|-----------------|
| **Stakeholders Needs** | Stakeholder requirements + governance in README; Cypilot ID traceability |
| **System Requirements** | Layered approach (global + module); mandatory language, source, rationale |
| **Functional Requirements** | IDs, rationale, source, actors; implicit testing standard (90% coverage) |
| **Non-Functional Requirements** | Global baselines + module deviations; NFR allocation table in DESIGN |
| **Use Cases** | PRD use cases + FEATURE actor flows with API/DB touchpoints |
| **Interfaces** | Public Library Interfaces + External Interfaces sections; standard integration patterns |
| **Architecture Definition** | Vision, drivers, layers, NFR allocation, traceability |
| **Design Viewpoints/Views** | Explicit IEEE 42010 views; domain/component/sequence/deployment |
| **Architecture Decisions** | Context, drivers, options, consequences, confirmation, requirement traceability, status |
| **Traceability** | Cypilot ID system across all artifacts; bidirectional links |
| **Verification/Validation** | Acceptance criteria; implicit testing standard; ADR confirmation |
| **Lifecycle Coverage** | Project-wide semver + deprecation policy; documented in foundational docs |
| **Change Management** | Git/PR audit trail; ADR status/dates; governance vote/veto |
| **Operational Concept & Environment** | Architecture manifest defines runtime/OS/arch; module PRDs for deviations |
| **Constraints & Assumptions** | PRD assumptions + DESIGN constraints; spread but present |
| **Requirement Language & Quality** | Explicit rules (MUST/SHALL; no fluff); implicit testing standard |
| **Requirement Attributes & Allocation** | Source, rationale, actors; DESIGN drivers + NFR allocation; FEATURE "Implements/Touches" |
| **Open-Source Mono-Repo Practices** | PR-based review; Cypilot IDs; documented in README |
| **CI-Based Cross-Validation** | Deterministic Cypilot validation; implicit via assumptions |

**Overall**: The spec system is **strongly aligned** with ISO 29148 while remaining pragmatic for an open-source library mono-repo. The layered approach (global guidelines + gear-specific deviations) is **scalable and maintainable**.
