Skip to content

CLAUDE.md

Latest commit

 

History

History
429 lines (341 loc) · 63.3 KB

CLAUDE.md

File metadata and controls

429 lines (341 loc) · 63.3 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TuiVision is a C#/.NET 10 port of the Turbo Vision 2.0.3 TUI framework (originally C/C++). The original source lives in tv203s/ as the conceptual reference; the C# port is a managed, modernized interpretation — not a line-for-line translation.

Commands

# Restore, build, and test (full validation cycle)
dotnet restore
dotnet build --configuration Release
dotnet test

# Run tests for a specific project
dotnet test tests/TuiVision.Core.Tests/

# Run a single test method
dotnet test --filter "FullyQualifiedName~TestMethodName"

# Build generated docs plus Playwright + axe accessibility smoke tests
cd tests/web-a11y
npm install
npx playwright install chromium
npm run test:docfx

# After every DocFX regeneration, rerun the matching A11y smoke check
docfx docfx.json
cd tests/web-a11y
npm run test:docfx

Architecture

Module Structure

Module Purpose
src/TuiVision.Core Foundation types: TPoint, TRect, TEvent, TObject
src/TuiVision.Controls UI components: TView (base for all visual elements)
src/TuiVision.Drivers.Console Console rendering: TConsoleBuffer, TConsoleDriver, IConsolePresenter
src/TuiVision.Serialization Binary archive system with polymorphic TRecordRegistry
src/TuiVision.Compatibility Key code translation from .NET keys to Turbo Vision scan codes

Key Design Patterns

  • Event system: TEvent uses static factory methods (TEvent.CreateKeyDown(...)) and readonly record struct payloads. Events are dispatched via TView.HandleEvent().
  • Coordinate system: TRect uses inclusive top-left, exclusive bottom-right bounds. Views maintain local coordinates; MakeLocal/MakeGlobal convert between coordinate spaces.
  • Console rendering: Presenter pattern — TConsoleDriver manages a back-buffer and publishes snapshots via IConsolePresenter, keeping rendering backends swappable.
  • Serialization: Envelope-based binary format (type ID + payload). Types register themselves with TRecordRegistry for polymorphic deserialization.
  • Lifecycle: TObject.ShutDown() for logical teardown + IDisposable for resource cleanup.

Global Build Settings (Directory.Build.props)

All projects share: net10.0, LangVersion: latest, Nullable: enable, ImplicitUsings: enable.

Repo Version Scheme — Directory.Build.props carries the repo-wide Version, AssemblyVersion, and FileVersion values for all projects and follows Major.Minor.Patch.Build:

  • Minor = current Spec-Kit feature/branch number, interpreted numerically as the canonical PR number for versioning (007 -> 7) and used immediately even before a GitHub PR exists
  • Patch = current commit count in that feature/PR branch (after committing the current change)
  • Build = manual build counter incremented before every dotnet build or dotnet test

Align the three version fields in Directory.Build.props whenever a commit is created or the branch is updated on a numbered Spec-Kit branch, before pushing.

Testing

Tests use MSTest. Test projects mirror source projects (e.g., TuiVision.Core.Tests → TuiVision.Core). TuiVision.Examples.SmokeTests is for integration-level tests of ported example programs.

Coverage Gate (SC-003): TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, and TuiVision.Drivers.Console must each achieve ≥ 70 % Line Coverage (Pflichtenheft §9.4 Nr. 1). Measure from the repository root with Coverlet (coverlet.collector): dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings. coverlet.runsettings is the canonical TuiVision coverage-gate configuration and MUST be kept in sync when gate-relevant assemblies, example assemblies, or test projects are added, renamed, or removed. Validate it with xmllint --noout coverlet.runsettings where available before relying on the coverage gate. Do not merge to main without passing this gate.

Documentation

  • Use System.Text.Json for project-owned JSON parsing and serialization.
  • Introduce Newtonsoft.Json only with documented justification and explicit reviewer approval.
  • Explanatory documentation must be bilingual (German first, English second) with CEFR-B2 readability.
  • Large normative documents such as Pflichtenheft*.md and Lastenheft*.md may use a synchronized English sidecar with suffix .EN.md instead of an oversized inline-bilingual file; the German version remains canonical unless explicitly marked otherwise.
  • Programmierung #include<everyone> — Diese Lernbeispiele richten sich an Azubis (Fachinformatiker AE/SI) mit Deutsch und Englisch als Arbeitssprachen sowie an sehbehinderte Lernende, die mit Braille-Displays, Screen-Readern oder Textbrowsern arbeiten. Barrierefreiheit ist kein Nice-to-have, sondern Pflichtanforderung. Guides, statistics, examples, and generated API documentation must remain usable in text-first assistive setups such as Braille displays, screen readers, and text browsers.
  • Generated HTML documentation should target WCAG 2.2 conformance level AA as the accessibility baseline.
  • Prefer semantic headings, lists, tables, and ASCII/text-first diagrams; do not encode essential meaning only through color, layout, or pointer-only affordances.
  • Treat bilingual CEFR-B2 delivery and the documented A11Y proof path as formal completion criteria for learner-facing documentation and active requirement artifacts.
  • Public API changes must include complete XML documentation updates.
  • Run docfx docfx.json when root config exists and API/XML docs changed.
  • Keep the Playwright + @axe-core/playwright smoke tests in tests/web-a11y/ aligned with the current DocFX structure and representative pages; use lynx as an additional text-browser spot check when available.
  • Treat every successful docfx docfx.json regeneration as incomplete until the matching tests/web-a11y/ A11y smoke check has also passed in the same work item.
  • GitHub Pages is published from .github/workflows/pages.yml: build root docfx.json, run the tests/web-a11y/ Playwright + axe smoke path, upload _site/ as a Pages artifact, and keep _site/ plus generated api/*.yml files out of Git.

Reference Source

tv203s/contrib/tvision/ contains the original Turbo Vision 2.0.3 C/C++ source. Consult it when porting new classes or understanding original behavior. Do not modify files in tv203s/.

Historical Source Reference Policy

  • Fuer jede Spec-Kit-Feature-Implementierung, die historisch abgeleitetes Turbo-Vision-Verhalten portiert, erweitert, testet, dokumentiert oder korrigiert, muessen die relevanten historischen Implementierungsdateien unter tv203s/ als Read-only-Referenz geprueft werden. Das betrifft mindestens passende .c- und .cc-Dateien.

  • Falls Typen, Konstanten, Makros, Datenlayout, Vererbung, Funktionssignaturen oder Kontext nur ueber Deklarationen klar werden, muessen auch die relevanten C/C++-Header wie .h, .hpp oder .hh geprueft werden.

  • tv203s/ wird nicht veraendert. Die C#-Portierung bleibt eine moderne, idiomatische Umsetzung der historischen Absicht und keine mechanische 1:1-Uebersetzung.

  • spec.md, plan.md, tasks.md, Guides, PR-Evidence oder Architektur-/Security-Nachweise muessen bei relevanten Features festhalten, welcher historische Zweck uebernommen wird und welche wesentlichen nutzer- oder API-sichtbaren Abweichungen bewusst sind.

  • Wenn ein Feature keinen historischen tv203s-Bezug hat, genuegt ein kurzes N/A mit Begruendung in Plan, Aufgaben oder Evidence.

  • For every Spec-Kit feature implementation that ports, extends, tests, documents, or fixes historically derived Turbo Vision behavior, review the relevant historical implementation files under tv203s/ as read-only reference. This includes at least the matching .c and .cc files.

  • When types, constants, macros, data layout, inheritance, function signatures, or context are only clear from declarations, also review the relevant C/C++ headers such as .h, .hpp, or .hh.

  • Do not modify tv203s/. The C# port remains a modern idiomatic implementation of the historical intent, not a mechanical line-by-line translation.

  • For relevant features, spec.md, plan.md, tasks.md, guides, PR evidence, or architecture/security evidence must record which historical intent is followed and which material user-visible or API-visible deviations are intentional.

  • If a feature has no historical tv203s relevance, a short N/A rationale in plan, tasks, or evidence is sufficient.

Branching Convention

Feature branches use either the agent-prefixed form codex/<feature-description> (or another supported agent prefix such as claude/, gemini/, copilot/, opencode/) or the numbered Spec-Kit form NNN-short-description when the Spec-Kit workflow creates the branch. CI runs on pushes to main, master, codex/**, claude/**, gemini/**, opencode/**, and copilot/** branches. When a dedicated feature branch has implemented the requirements of a Lastenheft, rename that file to Lastenheft_<topic>.<feature-branch>.md so the delivered scope stays traceable.

Active Feature Context

004-editor-file-help-streams

  • Current implementation baseline: execute the phase-6 increment from specs/004-editor-file-help-streams/spec.md and specs/004-editor-file-help-streams/plan.md
  • Scope is limited to reusable framework components in src/TuiVision.Controls and src/TuiVision.Serialization: TEditor, TMemo, TFileEditor, TEditWindow, file/dialog/history helpers, help topics/viewers/windows, stream primitives, and named resource containers
  • Out of scope for this increment: example applications such as tvedit, bhelp, and helpdemo; driver consolidation; calculator/macros/OS-shell integrations; and unrelated specialized widgets
  • Editor flows must cover text editing, insert/overwrite behavior, clipboard-oriented actions, search/replace, modified-state handling, explicit safe-close decisions before unsaved changes are discarded, and distinct overwrite decisions when save conflicts occur
  • Integration coverage for this feature must explicitly include event-loop-aware shell interaction, focus transitions, menu execution, and dialog interaction rather than relying on those behaviors only implicitly
  • File flows must keep directory navigation, file lists, current file-information metadata, wildcard filtering, manual path entry, and history recall synchronized inside reusable dialogs
  • Help flows must support context-based topic lookup, cross-reference navigation, and fallback content for missing contexts
  • Stream/resource flows must preserve named lookup semantics and reject malformed persisted input explicitly, including truncated, trailing, unknown-type, and cyclic payload failures
  • Planning decisions now fixed for this feature: dedicated runtime help files, shared-reference preservation without cyclic-graph support, exact case-sensitive resource keys, LF default for new files, preserved line endings for loaded files, and explicit overwrite decisions after external file changes

005-driver-consolidation-m07

  • Current planning baseline: execute the Phase-7 increment from specs/005-driver-consolidation-m07/spec.md and specs/005-driver-consolidation-m07/plan.md
  • Scope is limited to the managed driver baseline in src/TuiVision.Drivers.Console, the supporting validation in tests/TuiVision.Drivers.Tests, and the proof ledger docs/porting-status.md
  • Out of scope for this increment: mandatory example waves, full closure of the Phase-8 entrance gate, new source modules, native bindings, and any one-to-one recreation of the historical per-OS driver split
  • The proof ledger must cover every historical .cc implementation file in tv203s/contrib/tvision/classes with one mandatory primary target, optional secondary targets, status, evidence, and rationale
  • Linux and Windows/WSL compatibility checks are required as reviewable evidence for this phase, but may still be manual or semi-automated rather than mandatory CI gates
  • Planning decisions now fixed for this feature: .cc files are the formal M-07 ledger scope, ancillary .c/.h files may appear only as rationale support, capability buckets replace per-OS lineage as the review model, and Phase 7 remains distinct from the later full Phase-8 gate closure

006-close-phase8-gate

  • Current planning baseline: execute the Phase-8 entrance-gate closure from specs/006-close-phase8-gate/spec.md and specs/006-close-phase8-gate/plan.md
  • Scope is limited to final M-07 proof closure plus the remaining gate evidence across docs/porting-status.md, Pflichtenheft.md, the existing module test projects plus any required Compatibility-focused validation additions, coverage evidence, formatting evidence, and API-documentation validation
  • Out of scope for this increment: any of the 25 mandatory example waves, substitute follow-on example scope from TVDEMOS/ or TVFM/, unrelated new framework features, and Phase-7 redesign beyond finalizing still-pending proof rows
  • Every historical .cc ledger row must end in portiert + getestet or bewusst ausgelassen + Begruendung; no provisional portiert + Test ausstehend state may remain after closure is claimed
  • Gate closure must package explicit build, full-test, coverage, formatting, and conditional API-doc evidence and keep example waves blocked until the closure is formally recorded
  • Planning decisions now fixed for this feature: docs/porting-status.md stays the authoritative M-07 ledger; TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, and TuiVision.Drivers.Console must each satisfy the explicit 70 % line-coverage gate with assembly-specific evidence; tests/TuiVision.Compatibility.Tests/ is the planned dedicated Compatibility fallback suite when shared tests are insufficient; placeholder-only or no-op-only modules cannot satisfy that gate; gate-scope removals must update the proof surfaces in the same change; skipped or ignored gate-scoped tests require recorded tracked-issue references; unresolved local-versus-CI coverage conflicts block closure; and the closure needs a dedicated gate-marker or commit reference

012-interactive-wave2-demos

  • Current implementation status: interactive Wave-2 demo polish is implemented on branch 012-interactive-wave2-demos; final validation evidence is tracked in specs/012-interactive-wave2-demos/pr-evidence.md.
  • Delivered scope is limited to making the eleven Wave-2 examples visibly operable at normal runtime: Clipboard, Demo, DlgDsn, DynTxt, InpLis, ListVi, ProgBa, Sdlg, Sdlg2, TCombo, and TProgB; matching event-loop smoke tests in tests/TuiVision.Examples.SmokeTests/; guides, README, pr-evidence.md, and proportional architecture/security/A11Y/statistics evidence.
  • Before wiring or accepting each example, review the relevant historical .c/.cc source and any important matching headers under tv203s/ as read-only reference, capture the original demo intent, and document intentional user-visible deviations in guide or PR evidence.
  • Every example must show first-screen purpose text, expose primary behavior through menu, keyboard, status, or command paths, and update visible text-first feedback after each demonstrated operation.
  • Primary smoke proof must run app.Run() or the equivalent real application loop with injected TEvent, command, or key events. Direct helper methods may support setup or supplemental assertions only.
  • examples/Demo is the P1 vertical slice and must prove at least three visible behaviors before the pattern is spread across the rest of the examples.
  • File/path and dialog-designer flows stay read-only toward user data: use source-controlled fixtures, fixed repository paths, or test temporary directories; do not read arbitrary user file contents or persist user history as proof.
  • Wave 3 and Wave 4 examples, mandatory mouse-only operation, broad framework redesign, new runtime dependencies, databases, external services, and DocFX publishing-model changes are out of scope.
  • Next open mandatory example scope after this feature is Wave 3: editor, file, help, and stream demos such as tvedit, bhelp, and helpdemo.

013-wave2-visual-component-remediation

  • Current implementation status: visual component remediation is implemented on branch 013-wave2-visual-component-remediation; final validation evidence is tracked in specs/013-wave2-visual-component-remediation/pr-evidence.md.
  • Scope is limited to the eleven Wave-2 examples: Clipboard, Demo, DlgDsn, DynTxt, InpLis, ListVi, ProgBa, Sdlg, Sdlg2, TCombo, and TProgB.
  • Shared runtime support for the remediated examples lives in examples/Shared/Wave2Runtime.cs and is linked into the eleven scoped example projects.
  • The primary parity proof is the visible UI composition itself: controls, dialogs, windows, view groups, scroll groups, progress displays, input/list/combo composition, or another stable visible runtime state.
  • Each example must use the three-layer model: visible main component, real TStatusLine feedback, and keyboard-reachable Help -> Description.
  • Primary smokes must drive the real app loop and combine concrete state assertions with view-tree proof plus buffer/cell rendered visibility proof at expected positions or regions.
  • Historical C/C++ sources under tv203s/ remain read-only intent references; intentional user-visible deviations must be documented in plan, tasks, guides, feature evidence, or PR evidence.
  • AI-SBOM is N/A for this feature while AI is only development/agent tooling; re-evaluate if runtime/product AI, models, datasets, AI infrastructure, or delivered AI components enter scope.
  • Wave 3/4 functionality, broad framework redesign, mandatory mouse-only operation, arbitrary user-file proof, external proof paths, persistent user history, databases, external services, and new runtime dependencies are out of scope.

Example Wave Delivery Pattern

  • Larger mandatory example waves should use a deliberate two-stage Spec-Kit delivery model when framework gaps, porting logic, and interactive runtime polish would otherwise be mixed in one feature.
  • Stage 1 is the functional port/proof feature: port historical example behavior, close framework prerequisites, expose deterministic headless or in-process smoke paths, add guides/evidence, and explicitly mark interactive runtime polish as follow-up when normal dotnet run --project examples/<Name> is not yet the final demonstration.
  • Stage 2 is the interactive showcase feature: wire the proven functions into visible menus, status lines, desktop controls, dialogs, keyboard paths, and scripted UI-event smoke tests so the example is useful for learners and manual reviewers.
  • Do not call an example wave fully learner-facing complete until Stage 2 is delivered, unless the scope explicitly defines the example as a minimal non-interactive proof.

Gemeinsame Governance-Ergaenzung / Shared Governance Addendum

  • Alle nutzerseitigen Artefakte muessen barrierefrei gedacht und geprueft werden: CLI-Ausgaben, Dokumentation, HTML, UI und generierte Templates; WCAG 2.2 Level AA ist die Standard-Basis, sobald die Kriterien auf das Artefakt anwendbar sind.

  • All user-facing artefacts must be designed and reviewed for accessibility: CLI output, documentation, HTML, UI, and generated templates; WCAG 2.2 Level AA is the default baseline wherever the criteria apply.

  • Fuer C#/.NET-Repositories gilt standardmaessig eine Thorsten-Solo-Basis von 125 Zeilen/Arbeitstag, sofern das Repo keinen abweichenden, begruendeten Wert dokumentiert.

  • The default Thorsten-solo baseline for C#/.NET repositories is 125 lines/workday unless the repository documents a justified deviation.

Active Technologies

  • C# latest (C# 14) / .NET 10 (net10.0) + TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, TuiVision.Drivers.Console, MSTest, Coverlet, docfx (004-editor-file-help-streams)
  • Real local file-system interaction plus persisted binary help/resource files; no database layer in this increment (004-editor-file-help-streams)
  • C# latest on .NET 10 (net10.0) + Existing modules TuiVision.Core, TuiVision.Controls, TuiVision.Drivers.Console, TuiVision.Serialization, TuiVision.Compatibility; MSTest; Coverlet via dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings; docfx for API documentation validation; GitHub Actions for existing CI (005-driver-consolidation-m07)
  • Source-controlled Markdown evidence in docs/porting-status.md; no database storage; compatibility evidence may include repository notes and command output references (005-driver-consolidation-m07)
  • C# latest on .NET 10 (net10.0) + TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, TuiVision.Drivers.Console, existing MSTest suites plus any required Compatibility-focused validation additions, Coverlet coverage evidence, dotnet format, docfx, Pflichtenheft.md, and docs/porting-status.md for the formal Phase-8 entrance-gate proof (006-close-phase8-gate)
  • Repository-visible proof artifacts only; no database layer and no example-application delivery in this increment (006-close-phase8-gate)
  • Source-controlled example projects under examples/; wave-1 examples (desklogo, msgcls, tutorial, videomode) delivered; 41 smoke tests green; next: Wave 2 Controls and Dialogs (007-port-wave1-examples)
  • C# latest on .NET 10 (net10.0) + Existing TuiVision.Core geometry/event/buffer types; existing TuiVision.Controls shell foundation (TView, TGroup, TProgram, TApplication, TMenuItem, TStatusItem, ShellCommandIds); MSTest; Coverlet via dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings; conditional docfx docfx.json; GitHub Actions for existing CI validation (008-controls-revision)
  • In-memory UI state only in production; source-controlled planning, tests, and proof artifacts in specs/, tests/, and docs/; no database or external service storage (008-controls-revision)
  • C# latest on .NET 10 (net10.0) + Existing TuiVision.Core geometry/event/buffer types; existing TuiVision.Controls shell and widget foundation from 008-controls-revision (TView, TGroup, TProgram, TApplication, TMenuItem, TStatusItem, ShellCommandIds, TInputLine, TListViewer, TListBox, TScrollBar, TScroller, TStringList, TFileInputLine, THistory, ManagedClipboard, TParamText, editor-oriented TIndicator as a contrast case only); MSTest; Coverlet via dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings; conditional docfx docfx.json; GitHub Actions plus existing example-smoke infrastructure for downstream wave-2 readiness (009-controls-widgets-and-collections)
  • In-memory UI state only in production; source-controlled planning, tests, proof artifacts, and already delivered downstream examples in specs/, tests/, docs/, and examples/; no database or external service storage (009-controls-widgets-and-collections)
  • C# latest on .NET 10 (net10.0) + Existing TuiVision.Core geometry/event/buffer types; existing TuiVision.Controls shell foundation delivered in 008-controls-revision (TView, TGroup, TProgram, TApplication, TMenuItem, TStatusItem, ShellCommandIds) plus existing widget/input primitives (TInputLine, TListViewer, TListBox, TScrollBar, TScroller, TStringList, TFileInputLine, THistory, ManagedClipboard, current TParamText, editor-oriented TIndicator as a contrast case only); MSTest; Coverlet via dotnet test --collect:"XPlat Code Coverage" --settings coverlet.runsettings; conditional docfx docfx.json; GitHub Actions and existing tests/TuiVision.Examples.SmokeTests/ infrastructure as downstream contex (009-controls-widgets-and-collections)
  • C# latest on .NET 10 (net10.0) + Existing TuiVision.Core geometry/event/buffer types; existing TuiVision.Controls shell, dialog, file, color, history, and widget types (TDialog, TFileDialog, TFileList, TDirListBox, TFileInfo, TFileInputLine, THistory, TColorDialog, TColorSelector, TMonoSelector, TColorGroup, TColorDisplay, TComboBox, TProgressBar, TParamText); existing TuiVision.Serialization archive/resource foundation (TRecordRegistry, TRecordSerializer, TBinaryArchiveReader, TBinaryArchiveWriter, TResourceFile, TResourceCollection, pstream family); MSTest; Coverlet; conditional DocFX and web A11Y smoke tooling (010-standard-dialogs-designer)
  • In-memory dialog state and session-only history; real local file-system metadata for file-listing/validation only; source-controlled tests/proof artifacts; minimal persisted dialog-description fixture through existing serialization/resource primitives; no database or external service storage (010-standard-dialogs-designer)
  • C# latest / C# 14 on .NET 10 (net10.0) + existing framework modules TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, TuiVision.Drivers.Console; new wave-2 example projects under examples/; existing tests/TuiVision.Examples.SmokeTests/; MSTest; Coverlet; conditional DocFX and web A11Y smoke tooling (011-port-wave2-examples)
  • Runtime example state is in memory; standard-dialog file flows use real local file-system metadata only; dlgdsn may use source-controlled dialog-description fixtures through existing Serialization/resource primitives; no database, external service, persisted user history, or new dependency planned (011-port-wave2-examples)
  • C# latest / C# 14 on .NET 10 (net10.0) + Existing TuiVision modules only: TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, TuiVision.Drivers.Console; existing MSTest and Coverlet test stack; existing DocFX plus Playwright/axe web A11Y tooling. No new runtime NuGet dependency is planned. (012-interactive-wave2-demos)
  • Runtime example state is in memory. Dialog-designer and file/path demonstrations use source-controlled fixtures, fixed repository paths, or test temporary directories. The examples must not persist user history, write user data as part of normal demonstration, read arbitrary user file contents as proof, or add a database/external service. (012-interactive-wave2-demos)
  • Runtime example state remains in memory. Controlled examples may use source-controlled fixtures, fixed repository paths, or test temporary directories for metadata, rendering, validation, or rejection proof. The feature must not add a database, external service, network dependency, persistent user history, or arbitrary user-file content reads. (013-wave2-visual-component-remediation)

007-port-wave1-examples

  • Current status: Wave 1 delivered (2026-03-28). desklogo, msgcls, tutorial (16 steps), videomode are ported, smoke-tested, and guide-documented.
  • Wave 1 scope: examples/Desklogo/, examples/MsgCls/, examples/Tutorial/, examples/Videomode/; shared smoke-test infrastructure in tests/TuiVision.Examples.SmokeTests/; guides in docs/guides/examples/.
  • Next open scope: Wave 2 – Controls and Dialogs (requires Controls/Dialog layer as prerequisite before planning starts).
  • Planning decisions now fixed: headless smoke seam via bool headless constructor parameter + GetEvent() override; in-process MSTest execution without external process spawning; bilingual German-first/English-second XML docs and comments at CEFR-B2; DisplayModeCoordinator.ProbeResizeSupport() cross-platform probe with CA1416 suppressed.

Recent Changes

  • 013-wave2-visual-component-remediation: Implemented visible main components or stable visual runtime states, real TStatusLine feedback, Help -> Description, shared examples/Shared/Wave2Runtime.cs, stricter app-loop rendered-visibility smokes, guides, README, architecture/security evidence, statistics, and PR evidence for all eleven Wave-2 examples.
  • 004-editor-file-help-streams: Added the phase-6 specification and requirements checklist for editor, file, help, stream, and resource components.
  • 004-editor-file-help-streams: Added plan.md, research.md, data-model.md, quickstart.md, and contracts/public-api.md; synchronized shared agent guidance to the post-plan baseline.
  • 004-editor-file-help-streams: Applied plan-review clarifications for safe-close vs. overwrite handling, wildcard-filtered file dialogs, explicit malformed-stream cases, and non-functional scope boundaries.
  • 004-editor-file-help-streams: Added explicit coverage of insert/overwrite plus clipboard editor actions, synchronized file-information state in dialogs, shell menu/status routing, and the full Core/Controls/Serialization coverage gate.
  • 004-editor-file-help-streams: Tightened the remaining integration-test expectations so event-loop dispatch, focus transitions, menu execution, and explicit dialog interaction are named directly in the feature artifacts.
  • 005-driver-consolidation-m07: Added the phase-7 specification and clarification set for managed driver consolidation, M-07 proof coverage, primary versus secondary ledger targets, and required Linux/Windows/WSL compatibility evidence.
  • 005-driver-consolidation-m07: Added plan.md, research.md, data-model.md, quickstart.md, and contracts/phase-7-proof-contract.md to define the capability-based driver consolidation approach, the formal .cc ledger scope, and the review contract for docs/porting-status.md.
  • 005-driver-consolidation-m07: Implemented Phase-7 consolidation: created DriverCapabilityMap.cs with 5 capability buckets, built docs/porting-status.md covering all 151 historical .cc files, added 5 new driver test files (30 tests passing), updated docs/guides/multi-mac-workflow.md with compatibility evidence, created checklists/phase-8-gate-review.md, updated Pflichtenheft.md marker to Phase-8 gate closure.
  • 006-close-phase8-gate: Added the Phase-8 entrance-gate specification and requirements checklist for final M-07 closure, removal of provisional ledger states, and explicit build/test/coverage/format/API-doc proof before example waves may start.
  • 006-close-phase8-gate: Synchronized the hard coverage rule to require TuiVision.Core, TuiVision.Controls, TuiVision.Serialization, TuiVision.Compatibility, and TuiVision.Drivers.Console each to reach at least 70 % line coverage across the shared agent guidance and gate-tracking artifacts.
  • 006-close-phase8-gate: Added plan.md, research.md, data-model.md, quickstart.md, and contracts/phase-8-gate-contract.md to define the final M-07 closure workflow, the 5x-70%-coverage gate, the full-suite validation package, and the dedicated closure-commit contract.
  • 006-close-phase8-gate: Refined the plan after clarification so the five-module coverage gate now requires assembly-specific reporting and rejects placeholder-only or no-op-only closure modules.
  • 006-close-phase8-gate: Analyse-Remediation nach der Task-Pruefung nachgezogen: gate-docs.md als Planartefakt explizit benannt, tests/TuiVision.Compatibility.Tests/ als feste Plan-Baseline aufgenommen und Skip/Ignore-Faelle nur noch mit dokumentierter Tracking-Issue-Referenz als gate-konform zugelassen.
  • 007-port-wave1-examples: Wave 1 portiert: desklogo (minimale Desktop-App), msgcls (Broadcast-Nachrichtenrouting), tutorial (16 token-basierte Schritte), videomode (Faehigkeitserkennung + Fallback). 41 Smoke-Tests gruen, Release-Build sauber, dotnet format --verify-no-changes bestanden. Pflichtenheft.md Welle-1-Checkliste abgehakt, >>> NAECHSTER SCHRITT <<< auf Welle 2 vorgeschoben.
  • 008-controls-revision: Controls-Revision implementiert: TSubMenu, TStatusDef, WindowFlags neu hinzugefuegt; TMenuBar, TStatusLine, TWindow, TDialog, TMenuItem, TView erweitert; 338 Tests gruen, TuiVision.Controls-Abdeckung 84,02 %, Format-Gate bestanden; docs/porting-status.md, Pflichtenheft.md und docs/project-statistics.md nachgezogen; Lastenheft_ControlsRevision.md umbenannt.
  • 010-standard-dialogs-designer: Framework-Readiness fuer Standarddialoge und Dialog-Designer implementiert: explizite Datei-/Verzeichnisentscheidungen ohne Dateiinhalt-I/O, Color-/Display-/symbolische Charset-Auswahl, validierte Dialogbeschreibung, persistierter Dialogbeschreibungs-Roundtrip und malformed-input rejection; fokussierte Controls- und Serialization-Tests gruen.
  • 011-port-wave2-examples: Planartefakte fuer Welle 2 erstellt: 11 neue Beispielprojekte, dedizierte Example-Smoke-Tests, DE-first/EN-second Guides, Architektur-/Security-/A11Y-Nachweise und klarer sdlg/sdlg2-Scope als historische ScrollDialog/ScrollGroup-Beispiele.
  • 012-interactive-wave2-demos: Interaktive Showcase-Stufe fuer Welle 2 implementiert: alle elf Wave-2-Beispiele besitzen sichtbare normale Runtime-Pfade, app-loop-basierte Smoke-Nachweise, aktualisierte Guides, README-, Architektur-/Security-/A11Y- und PR-Evidence.

Agent File Synchronization Policy

  • When active feature context, implementation-plan guidance, or other shared AI-agent instructions change, update the following files together when affected:
    • AGENTS.md
    • CLAUDE.md
    • GEMINI.md
    • .github/copilot-instructions.md
    • .github/agents/copilot-instructions.md
  • Do not leave shared guidance synchronized in only one of these files.
  • If an agent-specific file needs intentional divergence, document the reason in the same change.

Project Statistics

  • Maintain docs/project-statistics.md as the living statistics ledger for the repository.
  • Update the file after each completed Spec-Kit implementation phase, after each agent-driven repository change, or when a refresh is explicitly requested.
  • Within the ## Fortschreibungsprotokoll table, keep entries in strict chronological order: oldest entry at the top, newest and most recently added entry at the bottom; entries with the same date keep their insertion order.
  • Keep a final top-level ## Gesamtstatistik block as the last section of docs/project-statistics.md; no later top-level section should follow it.
  • Inside that final ## Gesamtstatistik block, maintain compact ASCII-only trend diagrams that show at least the current artifact mix, the documented branch/phase curves, the documented acceleration factors from agentic-AI plus Spec-Kit/SDD support, and a direct comparison between experienced-developer effort, Thorsten-solo effort, and the visible AI-assisted delivery window; refresh them whenever the statistics ledger changes.
  • Keep each short CEFR-B2 explanation directly adjacent to its matching ASCII diagram group, ideally immediately before or after it, so apprentices do not need to scroll between explanation and diagram.
  • When the data benefits from progression across an X-axis, add simple ASCII X/Y charts as a second visualization layer; keep them approximate, readable in plain Markdown, and explained in CEFR-B2 language.
  • Keep the statistics section plain-text friendly for Braille displays, screen readers, and text browsers; the ASCII diagrams and their explanations must stay understandable without relying on color or visual layout alone.
  • When DocFX content, documentation navigation, or API presentation changes, validate representative _site/ pages through a text-oriented review path, preferably with a local Playwright accessibility snapshot.
  • Use WCAG 2.2 AA as the concrete review baseline for generated HTML documentation, especially for page language, bypass blocks, keyboard focus visibility, non-text contrast, and readable landmark structure.
  • Each update must capture branch/phase, observable work window, production/test/documentation line counts, main work packages, the conservative manual baseline of 80 code lines per day for an experienced developer, and the repo-specific Thorsten-Solo comparison baseline of 125 lines per workday for this Pascal/Turbo-Vision-derived port.
  • When reporting acceleration, compare both manual references against visible Git active days and label the result as a blended repository speedup rather than a stopwatch measurement.
  • When hour values are shown, convert the day-based estimates with the TVoeD working-day baseline of 7.8 hours (7h 48m) per day.

Workflow Platforms

  • The Multi-Mac setup on MacBook Air M2 and Mac mini M4 Pro is the primary development and day-to-day test workflow.
  • Keep gh, specify, codex, claude, copilot, and gemini installed on both Macs; before Spec-Kit work or Spec-Kit updates, run specify check to confirm the required toolchain is available.
  • After every /speckit-plan run or equivalent plan refresh that changes active technologies, project structure, or agent context, run .specify/scripts/bash/update-agent-context.sh for codex, claude, gemini, and copilot in the same work item by default. Treat this multi-agent context refresh as routine maintenance that does not need a separate user prompt.
  • Linux and Windows are additional compatibility-validation environments; on Windows, prefer WSL with a current Ubuntu release, currently Ubuntu 24.04.
  • When changes affect runtime behavior, build reliability, terminal behavior, or portability, include Linux and Windows/WSL compatibility checks where practical and reflect them in CI or equivalent validation evidence when feasible.

Pflichtenheft Next-Step Marker

  • Maintain a prominent >>> NAECHSTER SCHRITT <<< marker in Pflichtenheft.md.
  • The marker MUST point to the currently highest-priority open work item in the prioritized rest-work section and MUST be moved whenever progress changes the effective next step.

Shared Parent Guidance

  • The shared parent file /Users/thorstenhindermann/RiderProjects/AGENTS.md intentionally stores only repo-spanning baseline rules.
  • Keep repository-specific build, test, workflow, architecture, and feature guidance in this repository's own files; when both layers exist, the repository-local files are the more specific authority.

Level-2-Umgebungsregister / Level-2 Environment Registry

  • Die zentrale constitution.md enthält das verbindliche Level-2 Project Environment Registry.
  • Spec-Kit-Pläne und Claude-Arbeit in Level-2-Projekten müssen die passende Registry-Zeile als verbindlichen Kontext für Runtime, Build/Test, A11Y, Statistik und Agentenflächen verwenden.
  • Änderungen an einer Level-2-Runtime, Toolchain oder Statistik-Basis müssen constitution.md, .specify/memory/constitution.md und betroffene KI-Agenten-Dateien gemeinsam prüfen.

The central constitution.md contains the binding Level-2 Project Environment Registry. Spec-Kit plans and Claude work in Level-2 projects must use the matching registry row as binding context for runtime, build/test, A11Y, statistics, and agent surfaces. Changes to Level-2 runtime, toolchain, or statistics baselines require a joint review of constitution.md, .specify/memory/constitution.md, and affected AI-agent files.

Memory-Safe Languages (MSL) / Speichersichere Sprachen

  • Level-2-Projekte SOLLEN eine speichersichere Sprache (Memory-Safe Language, MSL) als primäre Laufzeit verwenden, wenn die Zielplattform es erlaubt.
  • Verbindliche MSL-Erlaubnisliste, Regeln und Begründungspflicht: siehe constitution.md, Prinzip XI.
  • MSL-Kurzliste: Rust, Swift, C#, F#, Java, Kotlin, Scala, Go, Dart, Python, Ruby, JavaScript, TypeScript, Haskell, OCaml, Erlang, Elixir, Ada, SPARK.
  • Nicht MSL (Begründung im Level-2-constitution.md erforderlich): C, C++, klassisches Objective-C, Assembly, cc65-C89, Zig (pre-1.0), Nim (manual), D ohne GC.
  • In Nicht-MSL-Repositories (z. B. C64Projects/cc65) die im Level-2-constitution.md hinterlegte Begründung im Plan- und Task-Kontext erwähnen.
  • speckit.constitution und speckit.specify SOLLEN bei Nicht-MSL-Primärsprache einen nicht blockierenden Hinweis ausgeben (Tooling-Aufgabe, separate Umsetzung).
  • Änderungen an dieser Empfehlung erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

Level-2 projects SHOULD use a memory-safe language (MSL) as their primary runtime when the target platform allows. Authoritative rules: constitution.md, Principle XI. MSL short list: Rust, Swift, C#/F#, Java/Kotlin/Scala, Go, Dart, Python, Ruby, JavaScript/TypeScript, Haskell, OCaml, Erlang/Elixir, Ada/SPARK. Non-MSL languages (C, C++, Assembly, cc65, Zig pre-1.0, …) require a documented justification in the Level-2 constitution.md. In non-MSL repositories (e.g. C64Projects/cc65), surface the documented justification in plans and tasks. speckit.constitution and speckit.specify SHOULD emit a non-blocking advisory warning when the primary language is not an MSL — tracked as a separate tooling task. Changes to this recommendation require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Sichere Code-Erzeugung / Secure Code Generation (ISO 27001/27002 A.8.28)

  • KI-generierter und menschlich geschriebener Code MUSS den etablierten Secure-Coding-Best-Practices der Zielsprache und des Frameworks folgen. LLMs erzeugen nicht zuverlässig sicheren Code; explizite Durchsetzung ist erforderlich.
  • Verbindliche Regeln und sprachspezifische Anforderungen: siehe constitution.md, Prinzip XII.
  • Sprachspezifische Kurzregeln (Detailprofil: .specify/templates/secure-coding-language-rules-template.md):
    • C / C89: Bounds-Checking, kein gets(), kein ungeprueftes sprintf()/strcpy(), CERT C.
    • C# / .NET: parametrisierte Queries, Output-Encoding gegen XSS, Anti-Forgery-Tokens, sichere Deserialisierung, Microsoft Secure Coding Guidelines.
    • Rust: unsafe isolieren und begruenden, keine Panic-Pfade aus nicht vertrauenswuerdigem Input, Deserialisierung validieren, cargo audit oder gleichwertig verwenden.
    • Go: HTTP-/Client-Timeouts setzen, context propagieren, SSRF pruefen, crypto/rand nutzen, govulncheck oder gleichwertig verwenden.
    • Swift: keine Force-Unwraps auf nicht vertrauenswuerdigen Daten, dekodierte Eingaben validieren, Keychain/CryptoKit/TLS-Defaults nutzen, Datei-URLs einschraenken.
    • Java / Kotlin: DTOs validieren, Persistence-Zugriffe parametrisieren, Deserialisierung beschraenken, Auth/CSRF/CORS/Session-Defaults pruefen.
    • Python: Boundary-Input validieren, keine unsichere Deserialisierung oder dynamische Ausfuehrung, subprocess/Dateipfade einschraenken, Dependency-Audit nutzen.
    • TypeScript / JavaScript: Runtime-Input validieren, XSS/Prototype-Pollution/SSRF pruefen, keine dynamische Code-Ausfuehrung, Lockfiles auditieren.
    • SQL: nur parametrisierte Statements, kein dynamisches SQL aus nicht vertrauenswuerdigem Input.
    • Bash: Variable in Anfuehrungszeichen ("$var"), kein eval auf nicht vertrauenswuerdigem Input, -- End-of-Options.
    • PowerShell: Set-StrictMode -Version Latest, validierte Parameter, kein Invoke-Expression auf nicht vertrauenswuerdigem Input.
  • Kryptografie: aktuelle Algorithmen (AES-256, RSA >= 3072, SHA-256+, Ed25519); veraltete (MD5, SHA-1 für Signaturen, DES, RC4) nur mit expliziter Risikobegründung.
  • Fehlerbehandlung darf keine internen Zustände, Stack-Traces oder Verbindungszeichenketten an Endbenutzer preisgeben.
  • Hinzugefügte Abhängigkeiten müssen aktiv gepflegt sein und dürfen keine bekannten kritischen CVEs aufweisen.
  • Code-Reviews MÜSSEN eine Sicherheitsperspektive für Eingabeverarbeitung, Authentifizierung, Autorisierung, Kryptografie und Datei-/Netzwerk-I/O enthalten.
  • Änderungen an dieser Regel erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

AI-generated and human-written code MUST follow the secure-coding best practices of the target language and framework. Authoritative rules: constitution.md, Principle XII, and .specify/templates/secure-coding-language-rules-template.md. Language-specific short rules cover C/C89, C#/.NET, Rust, Go, Swift, Java/Kotlin, Python, TypeScript/JavaScript, SQL, Bash, and PowerShell. MSL status does not replace secure API, I/O, auth, SQL, crypto, logging, or dependency review. Cryptography: use current algorithms (AES-256, SHA-256+, Ed25519); deprecated (MD5, SHA-1 for signatures, DES, RC4) only with explicit risk acknowledgement. Error handling must not expose internals. Dependencies must have no known critical CVEs. Code reviews must include a security perspective for input handling, auth, crypto, and I/O. Changes require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Sichere Software-Architektur / Secure Software Architecture (ISO 27001/27002 A.8.27)

  • KI-generierte und menschlich geschriebene Software-Architektur MUSS etablierten sicheren Architekturprinzipien folgen. Sicherer Code (Prinzip XII) ohne sichere Architektur reicht nicht aus — beide Ebenen müssen zusammenwirken.
  • Verbindliche Regeln und sprachspezifische Architekturvorgaben: siehe constitution.md, Prinzip XIII.
  • Verbindliche Architekturprinzipien:
    • Trust Boundaries: Explizite Vertrauensgrenzen definieren; alle Eingaben an Vertrauensgrenzen validieren und bereinigen.
    • Defense in Depth: Mindestens zwei unabhängige Sicherheitsschichten für kritische Assets.
    • Least Privilege: Jede Komponente, jeder Dienst und Prozess arbeitet mit minimalen Berechtigungen.
    • Fail-Safe Defaults: Zugriff standardmäßig verweigern, explizit gewähren; Fehlerpfade fallen in sicheren Zustand zurück.
    • Angriffsfläche reduzieren: Ungenutzte Endpunkte, Dienste und Debug-Funktionen deaktivieren oder entfernen.
    • Separation of Concerns: Authentifizierung, Autorisierung, Logging und Eingabevalidierung als Cross-Cutting Concerns implementieren, nicht ad-hoc verstreuen.
    • Sichere Konfiguration: Secrets in plattformgeeigneten Secret-Stores (z. B. Azure Key Vault, macOS Keychain), nie im Quellcode oder in Git-tracked Config-Dateien.
    • Supply-Chain-Sicherheit: Abhängigkeiten aus verifizierten Registries; Lock-Files committen; verwundbare Abhängigkeiten vor Release ersetzen.
  • Änderungen an dieser Regel erfordern ein gemeinsames Update in constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md und .github/copilot-instructions.md.

AI-generated and human-written software architecture MUST follow secure-architecture principles. Authoritative rules: constitution.md, Principle XIII. Core principles: trust boundaries (validate all input at system boundaries), defense in depth (at least two independent security layers), least privilege (minimum required permissions), fail-safe defaults (deny by default), attack surface reduction (disable unused features), separation of concerns (auth/logging/validation as cross-cutting concerns), secure configuration (secrets in secret stores, never in code or Git), supply-chain security (verified registries, lock files, no known-vulnerable dependencies). Principles XII + XIII together form the complete secure-development approach: XII = tactical code-level security, XIII = strategic architecture-level security. Changes require a joint update across constitution.md, .specify/memory/constitution.md, and all four agent guidance files.

Allgemeine Architektur-Governance / General Architecture Governance (iSAQB / arc42)

  • Architektur MUSS als explizites Arbeitsergebnis behandelt werden, wenn Struktur, Schnittstellen, Qualitätsattribute, Laufzeitverhalten, Deployment, Wartbarkeit oder technische Schulden betroffen sind.
  • Verbindliche Regeln: siehe constitution.md, Prinzip XX; Architektur-Evidenz liegt standardmaessig unter docs/architecture/.
  • Relevante Artefakte: Architecture Vision, Context View, Building-Block View, Runtime View, Deployment View, Quality Scenarios, Architecture Decision Records und Architecture Risks/Technical Debt.
  • In spec.md, plan.md und tasks.md immer festhalten, ob Architektur-Evidenz erforderlich ist; N/A nur mit kurzer Begruendung.
  • Bei sicherheitsrelevanter Architektur zusaetzlich die Secure-Architecture- und Security-Evidenz aus docs/security/ anwenden.

Architecture MUST be treated as an explicit work product when structure, interfaces, quality attributes, runtime behavior, deployment, maintainability, or technical debt are affected. Authoritative rules: constitution.md, Principle XX. Default evidence lives under docs/architecture/: architecture vision, context, building blocks, runtime, deployment, quality scenarios, ADRs, and architecture risks/technical debt. spec.md, plan.md, and tasks.md must state whether this evidence applies; N/A requires rationale. Security-relevant architecture also uses the secure-architecture evidence under docs/security/.

Sicherheitsdokumentation / Security Documentation (XII–XVIII Extensions)

  • Jedes Level-2-Projekt MUSS die folgenden Sicherheitsdokumente pflegen, basierend auf den Templates in .specify/templates/:
    • Bedrohungsmodell / Threat Model (threat-model-template.md) — STRIDE-Methodik, Trust Boundaries, Risikobewertung, CAPEC-Referenzen (Prinzip XIII + XVII)
    • Security Architecture Decision Records (S-ADR) (adr-template.md) — architektonische Sicherheitsentscheidungen mit Compliance-Nachweis (Prinzip XIII)
    • arc42 Section 8 Sicherheits-Querschnittskonzepte (arc42-security-template.md) — Authentifizierung, Autorisierung, Verschlüsselung, Eingabevalidierung, Fehlerbehandlung, Logging, Abhängigkeiten, Deployment (Prinzip XIII)
    • Sicherheits-Checkliste / Security Checklist (security-checklist-template.md) — sprachspezifische Code-Review-Checkliste (Prinzip XII)
    • Abhängigkeits-Audit / Dependency Audit (dependency-audit-template.md) — CVE-Tracking, Lizenz-Compliance, Supply-Chain-Sicherheit (Prinzip XII)
    • Sicherheits-Qualitätsszenarien / Security Quality Scenarios (security-quality-scenarios-template.md) — iSAQB CPSA-F Qualitätsszenario-Methodik (Prinzip XII + XIII, SHOULD)
    • ASVS-Verifikation / ASVS Verification (asvs-verification-template.md) — OWASP ASVS Level, Scope und Evidenz (Prinzip XV, Web-/API-Projekte MUST)
    • Supply-Chain-Evidenz / Supply Chain Evidence (supply-chain-evidence-template.md) — SBOM, AI-SBOM, VEX, SLSA, OpenSSF Scorecard (Prinzip XVI, releasefähige Projekte MUST; AI-SBOM nur bei KI-Runtime-/Produktkomponenten)
    • Zero-Trust-Anwendbarkeit / Zero Trust Applicability (zero-trust-applicability-template.md) — NIST SP 800-207-Bewertung (Prinzip XVIII, verteilte Systeme SHOULD)
    • SAMM-Bewertung / SAMM Assessment (samm-assessment-template.md) — OWASP SAMM Reifegrad und Verbesserungsplan (Prinzip XVIII, langlebige Projekte SHOULD)
  • Projektspezifische Instanzen werden in docs/security/ gepflegt; S-ADRs als einzelne Dateien in docs/security/adr/.

Every Level-2 project MUST maintain security documents based on templates in .specify/templates/: threat model (STRIDE+CAPEC), S-ADRs, arc42 Section 8 security concepts, security checklist, dependency audit, security quality scenarios (SHOULD), ASVS verification (web/API MUST), supply-chain evidence (release-capable MUST; AI-SBOM when AI runtime/product components apply), Zero Trust applicability note (distributed systems SHOULD), and SAMM assessment (long-lived projects SHOULD). Project-specific instances live in docs/security/; S-ADRs in docs/security/adr/. See constitution.md, Principles XII–XVIII for authoritative requirements.

Sicherheitsstandards & Anwendbarkeit / Security Standards & Applicability

  • Vor jeder Level-2-Aufgabe die anwendbaren Sicherheitsstandards aus constitution.md, Prinzipien XIV-XVIII bestimmen und explizit benennen.
  • NIST SSDF und CWE Top 25 gelten immer für Level-2-Arbeit.
  • OWASP ASVS gilt für Web-, API-, HTTP- und authentifizierte Dienste; der gewählte ASVS-Level muss benannt werden.
  • SBOM gilt für releasefähige oder verteilbare Artefakte; VEX, wenn bekannte Schwachstellen in ausgelieferten oder geprüften Komponenten bewertet werden müssen.
  • AI-SBOM gilt projektartabhängig bei KI-Modellen, KI-Diensten, Trainings-/Embedding-Daten, Inferenz-Infrastruktur oder KI-Runtime-Komponenten im ausgelieferten oder betriebenen System; reine Entwicklungswerkzeug-Nutzung wird als N/A mit Toolchain-Begründung dokumentiert.
  • SLSA gilt als Soll-Vorgabe für CI/CD- oder veröffentlichte Artefakte; Zero Trust ist für verteilte, servicebasierte, cloudnahe oder remote-verwaltete Systeme explizit zu prüfen.
  • CAPEC soll in Bedrohungsmodellen für die risikoreichsten Angriffswege verwendet werden; OWASP SAMM soll für langlebige Projekte/Workspaces in Verbesserungspläne einfließen.
  • OWASP Cheat Sheet Series, OWASP Proactive Controls und bei öffentlichen OSS-Repositories oder kritischen Abhängigkeiten OpenSSF Scorecard sind als ergänzende Referenzen zu berücksichtigen.
  • Nichtanwendbarkeit immer als N/A mit kurzer Begründung dokumentieren; keine stillschweigende Auslassung.

At the start of every Level-2 task, determine and name the applicable security standards from constitution.md, Principles XIV-XVIII. NIST SSDF and CWE Top 25 always apply. OWASP ASVS applies to web/API/HTTP/auth-bearing services; SBOM applies to releasable or distributable artefacts; AI-SBOM applies when AI models, AI services, datasets, inference infrastructure, or AI runtime components are part of the released or operated system; VEX applies when known vulnerabilities in shipped/evaluated components need a disposition statement. SLSA is the target model for CI/CD and published artefacts; Zero Trust must be explicitly evaluated for distributed, service-based, cloud, or remotely managed systems. CAPEC, OWASP SAMM, OWASP Cheat Sheet Series, OWASP Proactive Controls, and OpenSSF Scorecard are supporting references where relevant. Record non-applicability as N/A with justification rather than omitting it silently.

Agentischer Security-Workflow / Agentic Security Workflow

  • In spec.md, plan.md und tasks.md die anwendbaren Standards samt Evidenzpfad festhalten.
  • Bei Bedrohungsmodellen STRIDE als Basis und bei risikoreichen Flows zusätzlich relevante CAPEC-Patterns verwenden.
  • Bei Web/API-Features den ASVS-Level und den Verifikationsumfang in docs/security/ oder gleichwertiger Projektdokumentation ablegen.
  • KI-Nutzung explizit klassifizieren: Entwicklungswerkzeug, keine KI im ausgelieferten/betriebenen System, oder KI-Runtime-/Produktkomponente; AI-SBOM entsprechend als N/A begründen oder in der Supply-Chain-Evidenz dokumentieren.
  • Bei Release-/Artefakt-Arbeit SBOM, AI-SBOM, VEX, Provenance/SLSA-Nachweise und gegebenenfalls OpenSSF Scorecard in Release- oder Sicherheitsdokumentation einplanen.
  • Bei Architekturänderungen Zero Trust-Anwendbarkeit und bei langlebigen Projekten SAMM-Folgeaktionen prüfen.
  • Default-Evidenzpfad: docs/security/asvs-verification.md, docs/security/supply-chain-evidence.md, docs/security/zero-trust-applicability.md, docs/security/samm-assessment.md; Abweichungen nur mit lokal dokumentierter Begründung.

Capture the applicable standards and the evidence path in spec.md, plan.md, and tasks.md. Use STRIDE as the base for threat modeling and add relevant CAPEC patterns for the highest-risk flows. For web/API work, record the chosen ASVS level and verification scope in docs/security/ or equivalent project documentation. Classify AI usage as development tooling, absent from the released/operated system, or AI runtime/product component; document AI-SBOM as N/A or as supply-chain evidence accordingly. For release and artefact work, plan SBOM, AI-SBOM, VEX, provenance/SLSA evidence, and OpenSSF Scorecard review where applicable. For architectural changes, evaluate Zero Trust; for long-lived projects, consider OWASP SAMM follow-up actions. The default evidence path is docs/security/asvs-verification.md, docs/security/supply-chain-evidence.md, docs/security/zero-trust-applicability.md, and docs/security/samm-assessment.md, unless the repository documents a justified equivalent location.

GitHub/GitLab CLI First / GitHub/GitLab CLI zuerst

Für GitHub-Repositories zuerst die authentifizierte gh CLI für mögliche Schreibaktionen und Live-Repository-Operationen verwenden, einschließlich PR-/Issue-Kommentaren, PR-Statusprüfungen, Review-Follow-up, Workflow-Prüfung und Merge-/Statusabfragen. GitHub-Connector-Tools hauptsächlich für strukturierte Read-only-Inspektion oder Fälle nutzen, in denen die CLI nicht geeignet ist.

Für GitLab-Repositories die authentifizierte glab CLI zuerst für gleichwertige Aktionen verwenden. Bekanntermaßen fehlschlagende Connector-Schreibwege nicht wiederholt versuchen, wenn gh/glab die Aufgabe direkt erledigen kann.

For GitHub repositories, use the authenticated gh CLI first for feasible write actions and live repository operations, including PR/issue comments, PR status checks, review follow-up, workflow inspection, and merge/status queries. Use GitHub connector tools mainly for structured read-only inspection or when the CLI is not suitable.

For GitLab repositories, use the authenticated glab CLI first for equivalent actions. Do not repeatedly try connector write paths that are known to fail when gh/glab can perform the task directly.

Spec-Kit-Modell-Routing / Spec Kit Model Routing

  • Modellwahl ist operative Agenten-Routing-Guidance, keine Feature-Anforderung. Modellnamen nicht in spec.md, plan.md, tasks.md oder einzelne Feature-Specs schreiben; diese Artefakte muessen reproduzierbar bleiben, auch wenn Modellnamen wechseln oder ein anderer KI-Agent verwendet wird.
  • Der jeweilige Agent soll diese Empfehlungen auf seine aktuell verfuegbaren Modelle abbilden; keine feste Anbieter- oder Modellbindung ableiten.
  • Fuer Spec-Kit-Spezifikation, Klaerung, Planung, Tasks und Analyse (/speckit-specify, /speckit-clarify, /speckit-plan, /speckit-tasks, /speckit-analyze; je nach Agent auch /speckit.specify usw.) das staerkste verfuegbare Frontier-Reasoning-/Coding-Modell bevorzugen.
  • Fuer vollstaendige, lang laufende /speckit-implement-Laeufe das staerkste verfuegbare Long-Running-Agent-Modell bevorzugen; das Frontier-Modell nutzen, wenn maximale Urteilsguete wichtiger ist als Laufzeitstabilitaet.
  • Fuer fokussierte Reviews oder CI-Fixes ein coding-optimiertes Modell bevorzugen.
  • Fuer triviale Bereinigung, Formatierung oder risikoarme mechanische Edits ist ein schnelles kleines Coding-Modell akzeptabel.

Model choice is operational agent-routing guidance, not a feature requirement. Do not pin model names in spec.md, plan.md, tasks.md, or individual feature specs; those artifacts must stay reproducible even when model names change or another AI agent is used. Each agent should map these recommendations to its currently available models; do not derive a fixed vendor or model requirement. For Spec-Kit specification, clarification, planning, task generation, and analysis (/speckit-specify, /speckit-clarify, /speckit-plan, /speckit-tasks, /speckit-analyze; or /speckit.specify etc. depending on the agent surface), prefer the strongest available frontier reasoning/coding model. For complete long-running /speckit-implement runs, prefer the strongest available long-running agent model; use the frontier model when maximum judgment quality is more important than runtime stability. For focused review or CI fixes, prefer a coding-optimized model. For trivial cleanup, formatting, or low-risk mechanical edits, a fast small coding model is acceptable.

Spec-Kit-Preset-Pflege / Spec Kit Preset Maintenance

  • Standard-Preset-Set: security-governance v0.4.0 prio 10, architecture-governance v0.2.0 prio 20, isaqb-architecture-governance v0.1.0 prio 30, a11y-governance v0.2.0 prio 40, cross-platform-governance v0.1.0 prio 50, agent-parity-governance v0.1.0 prio 60.
  • security-governance v0.4.0 fuehrt AI-SBOM weiter als bedingt anwendbare Supply-Chain-Evidenz und ergaenzt sprachspezifische Secure-Coding-Profile fuer Rust, Go, Swift, Java/Kotlin, Python und TypeScript/JavaScript. Reine Entwicklungswerkzeug-Nutzung bleibt N/A; KI-Runtime-/Produktkomponenten benoetigen Evidenz nach G7/BSI AI-SBOM-Clustern.
  • Alle sechs Presets sind seit 2026-05-04 im github/spec-kit Community-Katalog enthalten und liegen zusätzlich als veröffentlichte Repos unter https://github.com/hindermath/spec-kit-preset-*.
  • Neue Level-2-Projekte SOLLEN bei der Spec-Kit-Initialisierung die passende Preset-Teilmenge installieren; C#/.NET-Level-2-Projekte verwenden standardmäßig alle sechs Presets, sofern keine begründete Ausnahme dokumentiert ist.
  • Referenz-Rollout für alle sechs Presets: RiderProjects/TinyPl0, RiderProjects/TinyCalc, RiderProjects/TuiVision, RiderProjects/InventarWorkerService.
  • Installation bevorzugt über den Community-Katalog, wenn specify das unterstützt; für reproduzierbare Pins die versionierten GitHub-ZIP-URLs aus constitution.md/README.md verwenden.
  • .specify/presets/ und generierte Agenten-/Command-Dateien committen, wenn Presets Projekt-Policy sind; .specify/presets/.cache/ nie committen.
  • Nach Installation oder Update prüfen: specify preset list, mindestens ein specify preset info <id>, bei Template-Fragen zusätzlich specify preset resolve <template>.
  • Die lokale Arbeitskopie der veröffentlichten Preset-Repos liegt unter ~/SpecKitPresetProjects/; kanonische Scaffolds in diesem Repo liegen unter specs/spec-kit-presets/ und specs/spec-kit-preset-repos/.
  • Verbesserungen an Presets zuerst im home-baseline-Scaffold einarbeiten, dann in die passenden Repos unter ~/SpecKitPresetProjects/ übertragen, committen, pushen und mit GitHub-ZIP-URL smoke-testen.
  • Bei Änderungen an Preset-Regeln immer prüfen, ob constitution.md, .specify/memory/constitution.md, AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md und scripts/templates/* ebenfalls aktualisiert werden müssen.
  • Community-/Katalog-Abstimmung läuft über github/spec-kit#2362.

Standard preset set: security-governance v0.4.0 prio 10, architecture-governance v0.2.0 prio 20, isaqb-architecture-governance v0.1.0 prio 30, a11y-governance v0.2.0 prio 40, cross-platform-governance v0.1.0 prio 50, and agent-parity-governance v0.1.0 prio 60. security-governance v0.4.0 keeps conditional AI-SBOM evidence and adds language-specific secure-coding profiles for Rust, Go, Swift, Java/Kotlin, Python, and TypeScript/JavaScript: development-tool-only AI usage is N/A, while AI runtime/product components require G7/BSI AI-SBOM cluster evidence. All six presets are in the github/spec-kit community catalog as of 2026-05-04 and are also published under https://github.com/hindermath/spec-kit-preset-*. New Level-2 projects should install the applicable subset; C#/.NET Level-2 projects default to all six unless a justified exception is documented. Commit .specify/presets/ and generated agent command updates when presets are project policy, but never commit .specify/presets/.cache/. Verify installs with specify preset list, specify preset info, and where relevant specify preset resolve. Improve presets in the home-baseline scaffold first, propagate to standalone preset repos, then commit, push, and smoke-test via GitHub ZIP URL. Preset-rule changes require reviewing constitution, all agent guidance files, and relevant templates. Community/catalog coordination happens in github/spec-kit#2362.

Hinweise / Notes

  • Diese Datei ergaenzt die projektspezifische Dokumentation mit agentischen Arbeitsregeln.
  • This file complements the project-specific documentation with agent-oriented working rules.

For additional context about technologies to be used, project structure, shell commands, and other important information, read specs/013-wave2-visual-component-remediation/plan.md.