fix(spec): QM audit remediation — German duties, missing stories, link separators

[hubertusgbecker]

Summary

QM audit remediation across all three specification levels. This PR fixes
structural gaps found during an independent quality audit of the specification
hierarchy. All fixes are targeted and non-destructive — no spec IDs are renamed
or removed, no behavior is changed.

---

Problem Statement

The specification hierarchy had four classes of structural defects that silently
degraded spec quality and build reliability:

Class	Scope	Impact
German Duties sections	10 L0 user stories	Inconsistent language — spec body in German while all other content is in English
Non-human actors	2 skill stories	Story format violation — user stories must describe human (or user-role) intent
Missing user story files	SYSP_US_INSTALLER, SYSP_US_JARVIS, SYSP_US_SCHEMA	sphinx-needs build error: existing reqs already link to SYSP_US_INSTALLER which did not exist
Semicolons in :links:	13 req files, 5 spec files	sphinx-needs syntax error: the correct multi-value separator for :links: is comma, not semicolon

Additionally, four targeted L2 spec gaps:

ID	Gap
SYSP_SPEC_CM_FRONTMATTER	syspilot.verify missing from CM agents list — verify engineer is a CM-dispatched engineer
SYSP_SPEC_VERIFY_FRONTMATTER	Status stuck at draft — content is fully specified and implemented
SYSP_SPEC_DESIGN_SOUL / SYSP_SPEC_DESIGN_DUTIES	Tags change → design — System Designer is a design domain agent, not a change domain agent
SYSP_SPEC_DOC_COPILOT_INSTRUCTIONS	Status open → draft — open is not a valid status in ubproject.toml

---

Changes

L0 — User Stories (13 files)

German duties → English (us_change_mgr, us_project_mgr, us_quality_mgr,
us_system_designer, us_dev_engineer, us_test_engineer, us_quality_mece,
us_release_engineer, us_verify_engineer, us_setup_engineer):

• German "verantwortlich für" block replaced with bullet-point English translation
• Content is semantically identical — only language changed

Non-human actors:

• us_skill_orchestration: "syspilot manager agent" → "syspilot user"
• us_skill_branching: "syspilot agent" → "syspilot user"

New story files:

• us_installer.rst — SYSP_US_INSTALLER: critical — 8 existing reqs in
  req_setup_engineer.rst already link to this ID; the missing file was a live
  sphinx-needs build error. The inline duplicate in us_setup_engineer.rst is
  removed and replaced with a cross-reference note.
• us_jarvis.rst — SYSP_US_JARVIS: documents the Jarvis inter-agent
  communication mechanism already referenced in PM/CM/QM agent frontmatters
• us_schema_check.rst — SYSP_US_SCHEMA: documents the QM schema validation
  check (third check in the MECE + Trace + Schema audit trio)

Semicolons in :links::

• us_skill_impact.rst: 3 semicolons → commas

Index update: us_installer, us_jarvis, us_schema_check added to
userstories/index.rst

---

L1 — Requirements (14 files)

Semicolons → commas in :links: (sphinx-needs requires comma as separator):

File	Instances fixed
req_project_mgr.rst	2
req_change_mgr.rst	2
req_quality_mgr.rst	2
req_setup_engineer.rst	2
req_dev_engineer.rst	1
req_verify_engineer.rst	1
req_release_engineer.rst	1
req_quality_mece.rst	1
req_quality_trace.rst	1
req_test_engineer.rst	1
req_docu_engineer.rst	1
req_system_designer.rst	1
req_skill_impact.rst	1

New file: req_jarvis.rst with three requirements:

• SYSP_REQ_JARVIS_TOOL — the syspilot_jarvis_tools messaging tool
• SYSP_REQ_JARVIS_CONTRACT — message payload structure contract
• SYSP_REQ_JARVIS_FRONTMATTER — per-agent frontmatter declaration requirement

Index update: req_jarvis added to requirements/index.rst

---

L2 — Design Specs (5 files)

Semicolons → commas in :links: (5 files):
spec_agent_arch, spec_skill_ask_questions, spec_skill_branching,
spec_skill_orchestration, spec_skill_impact

Targeted spec fixes:

ID	Change
SYSP_SPEC_CM_FRONTMATTER	Add "syspilot.verify" to agents list
SYSP_SPEC_VERIFY_FRONTMATTER	status: draft → status: approved
SYSP_SPEC_DESIGN_SOUL	tags: …, change, soul → tags: …, design, soul
SYSP_SPEC_DESIGN_DUTIES	tags: …, change, duties → tags: …, design, duties
SYSP_SPEC_DOC_COPILOT_INSTRUCTIONS	status: open → status: draft

---

Verification

• Zero remaining :links: semicolons across all docs/syspilot/**/*.rst
• Zero remaining German duty sections in L0 user stories
• SYSP_US_INSTALLER exists as a standalone file and is removed from the inline position in us_setup_engineer.rst
• SYSP_US_JARVIS and SYSP_US_SCHEMA exist and are indexed
• SYSP_REQ_JARVIS_* files exist and link upward to SYSP_US_JARVIS
• syspilot.verify present in CM agents list
• No spec has status: open (not a valid status value)
• Branch base is development — no fork-specific commits included

---

Deferred (out of scope for this PR)

Item	Rationale
SYSP_REQ_INSTALLER_SOUL / SYSP_REQ_INSTALLER_FRONTMATTER additions	Upstream has significantly rewritten the installer req set; adding these would require coordinating with the ongoing installer work
req_jarvis.rst L2 design specs	Requires separate System Designer pass to design the Jarvis spec layer
Status promotions beyond SYSP_SPEC_VERIFY_FRONTMATTER	Require explicit review against implementation state

[enthali]

Thank you @hubertusgbecker — this is an impressive piece of work. A full independent QM audit across all three spec levels is exactly the kind of systematic quality review we've been wanting but haven't had bandwidth for. The findings are real and the fixes are correct.

What we've already addressed since you branched (2026-06-03):

Your branch is based on 338b5ba. Since then we shipped v0.6.0 and two post-release fixes. Some overlapping areas:

• The installer spec (spec_installer.rst) was substantially rewritten in v0.6.0 (installer-spec-rewrite CR) — there will be conflicts there
• The German duties in user stories: we had a agent-duties-english-translation CR in our backlog — not yet implemented, so your fixes are still needed there
• The semicolon → comma fixes: not yet addressed on our side — all yours

Request: please rebase onto current development

Could you rebase upstream-fix/spec-quality-full-audit onto the current development HEAD? That will surface any real conflicts so we can resolve them cleanly before merging. The bulk of your changes (semicolons, German duties, missing US files, new req_jarvis.rst) should come through conflict-free.

Once rebased, we'll review and merge — this is going into the next release.

Thanks again — this is exactly the kind of contribution that makes syspilot better for everyone using it.