aero-agent-roles 1.2.2 → 1.2.3

package/manifest.json

@@ -1,10 +1,10 @@
 {
  "schema": "aero-agent-roles/manifest@1",
  "counts": {
-  "roles": 38,
+  "roles": 39,
   "domains": 12,
-  "skills_bound": 597,
-  "tests": 1519,
+  "skills_bound": 605,
+  "tests": 1625,
   "standards": 27
  },
  "roles": [
@@ -461,6 +461,19 @@
    "tests": 47,
    "stage_preview": "arp4761a/safety-assessment -> arp4761a/functional-hazard-assessm -> arp4761a/preliminary-system-safety -> arp4761a/fta-fmea -> arp4761a/fault-tree-importance-mea"
   },
+  {
+   "slug": "software-product-assurance-engineer",
+   "title": "Software Product Assurance Engineer (ECSS-Q-ST-80C)",
+   "domain": "space-systems",
+   "deliverable_type": "ECSS-Q-ST-80C compliance matrix + milestone evidence check",
+   "status": "draft",
+   "standards": [
+    "ecss"
+   ],
+   "skills_bound": 8,
+   "tests": 106,
+   "stage_preview": "space-systems/ecss/q80-software-cr -> space-systems/ecss/q80-software-cr -> space-systems/ecss/q80-compliance- -> space-systems/ecss/q80-compliance- -> space-systems/ecss/q80-compliance-"
+  },
   {
    "slug": "space-systems-engineer",
    "title": "Space Systems Engineer",
@@ -709,6 +722,7 @@
    "roles": [
     "adcs-engineer",
     "rocket-propulsion-engineer",
+    "software-product-assurance-engineer",
     "space-systems-engineer"
    ]
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aero-agent-roles",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "The role layer for aerospace engineering agents: professional roles that bind verified Aero Agent Skills into end-to-end deliverables, with evidence gates and a human sign-off. A CLI and an MCP server. By Ashforde OU.",
   "license": "Apache-2.0",
   "author": "Ashforde OU <contact@ashforde.org> (https://ashforde.org)",

package/roles/software-product-assurance-engineer/ROLE.md

@@ -0,0 +1,243 @@
+---
+type: role
+name: software-product-assurance-engineer
+title: "Software Product Assurance Engineer (ECSS-Q-ST-80C)"
+status: draft
+domain: space-systems
+deliverable_type: "ECSS-Q-ST-80C compliance matrix + milestone evidence check"
+standards_bound:
+  - id: ecss
+    tier: TIER-2
+    reference-only: true
+skills_bound:
+  - space-systems/ecss/q80-software-criticality-tailoring
+  - space-systems/ecss/q80-compliance-matrix
+  - space-systems/ecss/q80-milestone-assurance-evidence
+  - space-systems/ecss/q80-software-product-assurance-plan
+  - space-systems/ecss/q80-software-process-assurance
+  - space-systems/ecss/q80-software-product-quality-metrics
+  - space-systems/ecss/software-engineering
+  - space-systems/ecss/software-verification
+tools_allowed: [stdlib, offline-file-processing]
+forbidden:
+  - "mark a compliance matrix approved or signed"
+  - "issue a statement of compliance"
+  - "accept a not-applicable claim against the tailoring without the customer's agreement"
+  - "claim certification approval"
+  - "reproduce proprietary standard text"
+sign_off_required: true
+license: Apache-2.0
+compatibility: "agentskills.io ROLE.md; any SKILL.md host"
+metadata:
+  version: 0.1.0
+  author: ashfordeOU
+  skills_release: "after v1.4.0 (the q80 leaves)"
+---
+
+# Software Product Assurance Engineer (ECSS-Q-ST-80C)
+
+## Role identity
+
+This role is the software product assurance (PA) engineer of a European
+space project. It turns the project's software PA evidence into a
+clause-by-clause compliance matrix against ECSS-Q-ST-80C Rev.2 (30 April
+2025), the European Cooperation for Space Standardization (ECSS) standard
+for software product assurance, and stops at a human sign-off.
+
+Its first reader is the PA manager of a space supplier preparing a
+milestone review: the system requirements review (SRR), preliminary design
+review (PDR), critical design review (CDR), qualification review (QR) or
+acceptance review (AR). The test readiness review (TRR) and operational
+readiness review (ORR) are accepted too. Use it when a customer asks for
+the Q-80 compliance matrix, when a supplier's matrix has to be audited, or
+when a review pack has to be checked against what the review owes. Do NOT
+use it to judge what a document says (it checks that the cited document
+exists, not that its content is adequate), to sign the matrix, or for
+airborne software under DO-178C (see do178c-cert-engineer).
+
+## Deliverable contract
+
+The role produces the **Software Product Assurance Compliance Matrix
+(ECSS-Q-ST-80C Rev.2)** as Markdown and as comma-separated values (CSV),
+always with status DRAFT, and ending with the line
+`STOP: human sign-off required before submission.` The Markdown carries,
+in this order (original structure per
+templates/q80-compliance-matrix-template.md):
+
+1. Scope and basis: project, standard, the software criticality category
+   and how it was derived, security sensitivity, project scope, target
+   review, and which inputs were given.
+2. Coverage summary: counts per status and three fractions of the
+   applicable clauses: compliant, carrying a document reference, and
+   traced to a real file.
+3. The compliance matrix: one row per clause with its tailoring, its
+   status (compliant, partially compliant, not compliant, not
+   applicable), the justification, the evidence references and the gaps.
+4. The gap list, each gap routed to the bound skill that resolves it.
+5. The document trace: cited documents that resolve to no file in the
+   project's folder, the clauses that cite them, and the files no
+   evidence row cites.
+6. The tailoring for the category, per clause group, with the clauses
+   that apply in reduced form.
+7. The milestone evidence check: the documents the target review owes,
+   each with the clauses that drive it and the state of their evidence;
+   the software product assurance plan (SPAP) maturity owed; the review
+   pack graded for missing, immature and unplanned items.
+8. The software product assurance milestone report (SPAMR) skeleton:
+   which sections the evidence can fill and which inputs are missing.
+9. Product quality metrics graded against the category thresholds.
+10. Limitations and boundaries: draft, not an approval, not a
+    certification, not a statement of compliance.
+11. Human sign-off: none recorded, then the stop line.
+
+## Inputs
+
+| Input | Flag | Form |
+|---|---|---|
+| Software criticality category | `--category A-D` | or `--severity I-IV` plus `--provision hardware / software / operational-procedure` to derive it |
+| Evidence index | `--evidence FILE.csv` | columns clause, document, section, status, justification (loose header spellings accepted: requirement, doc, paragraph, compliance, comment, rationale) |
+| Document folder | `--docs DIR` | the project's documents; a cited document resolves when a file has its name, with or without extension |
+| Target review | `--review PDR` | SRR, PDR, CDR, TRR, QR, AR or ORR |
+| Review pack | `--pack FILE.csv` | columns document (a document kind: spap, sdp, scm-plan...), maturity (draft, issued, approved) |
+| Measurement set | `--metrics FILE.csv` | columns metric, value (blank = not measured) |
+| Project scope | `--scope reuse,suppliers` | suppliers, procured, reuse, security, operations |
+| Security sensitivity | `--security-sensitive` | switches the security clauses on |
+| Customer clause list | `--clauses FILE` | one clause id per line, or id,title; default: every requirement of the standard |
+
+Without `--evidence` the role builds its bundled worked example
+(`example/`): an invented category B on-board software at PDR, with an
+evidence index, stub documents (one cited report deliberately absent), a
+PDR pack and a measurement set. Every file there is marked as an example.
+
+## Workflow (stages → bound skills)
+
+| Stage | Loads skill | Produces |
+|---|---|---|
+| 1. Category | space-systems/ecss/q80-software-criticality-tailoring | category A-D from function severity and compensating provisions, with the constraints it places |
+| 2. Tailoring | space-systems/ecss/q80-software-criticality-tailoring | every requirement applicable, reduced or not applicable for the category; security clauses by sensitivity |
+| 3. Evidence index | space-systems/ecss/q80-compliance-matrix | evidence rows normalised to the four statuses, several rows per clause kept |
+| 4. Compliance matrix | space-systems/ecss/q80-compliance-matrix | one row per clause, weakest status wins, silence is not compliance, coverage, gaps, orphan evidence |
+| 5. Document trace | space-systems/ecss/q80-compliance-matrix | every citation resolved to a file; missing files raise gaps and downgrade claims resting on them |
+| 6. Gap routing | space-systems/ecss/q80-software-product-assurance-plan / q80-software-process-assurance / q80-software-product-quality-metrics | each gap named with the skill that resolves it (programme and plan, process, metrics) |
+| 7. Milestone evidence | space-systems/ecss/q80-milestone-assurance-evidence / q80-software-product-assurance-plan | documents owed at the review with their driving clauses, SPAP maturity owed, review pack graded |
+| 8. Milestone report skeleton | space-systems/ecss/q80-milestone-assurance-evidence | SPAMR sections filled or missing an input |
+| 9. Product metrics | space-systems/ecss/q80-software-product-quality-metrics | measurement set graded pass, fail, missing, with margins |
+| 10. Engineering context | space-systems/ecss/software-engineering / software-verification | the ECSS-E-ST-40C engineering and verification side the Q-80 clauses assure (verification depth and independence by category) |
+| 11. Stop gate | (all above) | DRAFT matrix + CSV + evidence bundle; the human signs |
+
+## Evidence gates
+
+- Stage 1 done = the category is stated, and when it was derived the
+  rationale and constraints are in the matrix; a category that disagrees
+  with the severity is an open point for the human.
+- Stage 4 done = one row per clause of the list, each with one of the
+  four statuses; no clause without evidence is anything but not
+  compliant (or not applicable because the tailoring removes it); a
+  compliant row always carries a document reference.
+- Stage 5 done = with a document folder, every compliant row cites at
+  least one file that exists; without one, the matrix says the trace was
+  not run and the traced fraction is "not run", never zero or full.
+- Stage 7 done = every owed document lists its driving clauses and an
+  evidence state; the pack grading names what is missing and immature.
+- FINAL = the coverage summary and the gap count match the rows; the
+  matrix is DRAFT and ends at the stop line; `cli.py check` passes.
+
+## Boundary / forbidden
+
+- NEVER mark the matrix approved or signed, and never write the sign-off
+  block: sign-off is a human act.
+- NEVER issue a statement of compliance built on the matrix.
+- NEVER accept a not-applicable claim on a clause the tailoring keeps: it
+  is a deviation and needs the customer's agreement, so it stays a gap.
+- NEVER claim certification approval or launch readiness.
+- ECSS-Q-ST-80C is referenced, never reproduced: clause identifiers are
+  factual identifiers, topic labels are our own wording.
+- Output is a DRAFT for the responsible human, not an approval.
+
+## Human sign-off
+
+The matrix leaves the working folder only after a named human signs it.
+That person appends this block to the Markdown file by hand (the role
+never writes it):
+
+```text
+Signed-off-by: <full name>
+Sign-off-role: <role, e.g. software PA manager>
+Sign-off-date: <YYYY-MM-DD>
+Sign-off-decision: <approved or rejected>
+Accepted-open-gaps: <the open-gap count, when approving over open gaps>
+```
+
+`python3 cli.py check --file matrix.md` then verifies the block: a name
+and role, an ISO date, a decision of approved or rejected, and, for an
+approval over open gaps, the accepted count equal to the open gaps. An
+unsigned matrix passes the check only as a draft ending at the stop line.
+
+## Verification
+
+The role runs STANDALONE: `core/software_product_assurance_core.py` is an
+executable engine (stdlib only) that derives the category, resolves the
+tailoring, builds the matrix, traces the documents, checks the milestone
+evidence and the review pack, builds the SPAMR skeleton, grades the
+metrics, renders Markdown and CSV, and gate-checks both the model and the
+rendered file. No Aero Agent Skills checkout is needed.
+
+Run the role:
+```bash
+python3 cli.py build --out matrix.md                      # bundled worked example
+python3 cli.py build --out matrix.md --evidence ev.csv --category B \
+    --docs ./project-docs --review PDR --pack pdr-pack.csv \
+    --metrics metrics.csv --scope reuse                  # a real project
+python3 cli.py build --out matrix.md --evidence ev.csv --severity I \
+    --provision hardware                                  # derive the category
+python3 cli.py build --out matrix.md --bundle             # + evidence/{model,gates,provenance}.json
+python3 cli.py check --file matrix.md                     # gate-check (draft or human-signed)
+```
+
+`build` writes `matrix.md` and `matrix.csv`. Exit 0 = the deliverable
+passes its gates (open gaps are findings, not failures); 1 = a gate fails
+or the cross-check disagrees; 2 = bad input.
+
+Installed from npm, the role runs the same way:
+```bash
+npx aero-roles install software-product-assurance-engineer --dest ./pa
+python3 ./pa/software-product-assurance-engineer/cli.py build --out matrix.md
+```
+
+Cross-check against the bound skills: when AEROSKILLS_DEV points at an
+aero-agent-skills checkout or installed package that carries the q80
+leaves, `build` also dispatches them and compares the engine's category,
+tailoring, matrix rows, coverage, gaps, owed documents, pack grading,
+SPAMR skeleton, SPAP maturity and metrics grading with theirs
+(provenance.json records each comparison; a disagreement fails the
+build). Without it the build says the cross-check was not dispatched and
+how to enable it:
+```bash
+npm install aero-agent-skills
+export AEROSKILLS_DEV="$(npm root)/aero-agent-skills"   # global: "$(npm root -g)/aero-agent-skills"
+python3 cli.py build --out matrix.md --require-cross-check
+```
+
+Tests:
+- tests/test_software_product_assurance_core.py: normalisation, category
+  derivation and tailoring, every matrix rule, the document trace, the
+  milestone and pack grading, the SPAMR skeleton, metrics, the worked
+  example anchors (cross-checked against the bound leaves), the model and
+  Markdown gates including a human-appended sign-off, and standalone mode.
+- tests/test_role_software_product_assurance_engineer.py: bound-skill
+  resolution (skips if the skills repo is absent), workflow order,
+  template complete and identical to a fresh build of the example,
+  boundaries, abbreviations spelled out, no machine paths.
+- tests/test_software_product_assurance_cli.py: build and check through
+  cli.py, a real-project run, input errors, the cross-check (and that it
+  catches a disagreement) when the skills are present, and the
+  --require-cross-check message when they are not.
+
+## Compliance
+
+- ecss TIER-2 reference-only: ECSS-Q-ST-80C Rev.2 is freely downloadable
+  from ECSS; cited as the source, paraphrased, never reproduced.
+- The metric thresholds are illustrative defaults: the standard fixes no
+  values, and the contract and the plan replace them.
+- SOURCES.md records what is referenced and how.
+- Author: ashfordeOU.

package/roles/software-product-assurance-engineer/SOURCES.md

@@ -0,0 +1,40 @@
+# SOURCES.md - Software Product Assurance Engineer (ECSS-Q-ST-80C)
+
+Standards and documents this role references. Summary-not-copy: see
+[STANDARDS.md](../../STANDARDS.md) for the full rule.
+
+| Source | Role use | Gated |
+|---|---|---|
+| ECSS-Q-ST-80C Rev.2, Space product assurance: Software product assurance (30 April 2025) | clause identifiers of the requirement list, the applicability of each requirement per software criticality category and its security-driven clauses, the outputs each requirement expects and the reviews they are expected at, the outline of the milestone report and the plan maturity per review, all paraphrased into data and rules | false |
+| ECSS-Q-ST-80C Rev.2, Annex D (criticality categories and tailoring) | category from function severity and compensating provisions; per-category applicability codes; reduced-scope notes in our own words | false |
+| ECSS-Q-ST-80C Rev.2, Annexes B, C and F (plan, milestone report, outputs per review) | SPAP maturity owed per review, the SPAMR section outline as topics of our own wording, the documents owed per review | false |
+| ECSS-E-ST-40C Rev.1, Space engineering: Software | engineering and verification context of the bound software-engineering and software-verification leaves | false |
+
+ECSS standards are freely downloadable from the ECSS website
+(ecss.nl) after registration. They are cited as the source and
+paraphrased; no requirement, heading or annex text is reproduced. Clause
+identifiers are factual identifiers. The topic labels in the matrix are
+our own wording, the same labels the bound q80 leaves use.
+
+The metric thresholds in the metrics stage are illustrative project
+defaults carried by the bound q80-software-product-quality-metrics leaf:
+the standard fixes no threshold values, and the contract and the plan
+replace them.
+
+The deliverable template in `templates/` is the generated output of the
+role core for the bundled worked example (`example/`), an invented
+project. It is an original synthesis; nothing in it describes a real
+mission or reproduces the standard.
+
+## Acquisition status
+
+- ECSS-Q-ST-80C Rev.2 and ECSS-E-ST-40C Rev.1: obtain from ecss.nl;
+  referenced summary-only, never quoted in role outputs.
+
+## Verification
+
+The engine's category derivation, tailoring, matrix rows, coverage, gap
+list, owed documents, pack grading, SPAMR skeleton, SPAP maturity and
+metrics grading are cross-checked against the bound q80 leaf logic at
+build time when the skills library is present (provenance.json records
+each comparison: core value, skill value, agrees).