Technischer Überblick¶

Status: Entwurf

Wie die nächste Version (0.1) gebaut wird – für jede Version aktualisiert. Vorschläge von Claude, 2026-10-19; nichts auf diesen Seiten ist verbindlich, bis Daniel es freigibt. Fragen, die die Arbeit blockieren, sind in Offene Fragen gesammelt.

Ziel¶

Release 0.1 bauen (Roadmap): die CLI mit dem offenen Dateiformat, die Adapter für Markdown, rST/Sphinx-Needs und reinen Text sowie die Agent-Skills deciwa-work und deciwa-ask – gut genug, dass Daniel deciwa in seiner Wissensbasis statt [CHECK]-Markierungen nutzt.

Nicht in 0.1: push / pull, VS Code, Chrome, monsterbrain, gehosteter Dienst, Python-/HTML-Adapter, die eigenständige Engine. Das Design darf sie aber nicht blockieren – vor allem nicht das Review am Ergebnis (Reviews finden auf den Erge... (DEC_REVIEW_ON_RESULTS)) und Host-Apps (Host-Apps und die eigenständige Engine).

Architektur¶

Jedes Frontend – die Integrationen wie auch die Agent-Skills – spricht mit der deciwa-CLI und ihrer Core-Bibliothek, nie direkt mit den Dateien (Die CLI ist der Master, mit... (DEC_CLI_MASTER)). Die CLI speichert Reviews in .deciwa/ im Repository oder später im gehosteten Dienst.

Jedes Frontend spricht mit der CLI, nie direkt mit den Dateien.

Repository¶

deciwa/
├── packages/            one package per part – see below
│   ├── core/            deciwa-core     model, .deciwa/ store, engine
│   ├── server/          deciwa-server   review server
│   ├── cli/             deciwa-cli      the deciwa command
│   ├── ui/              deciwa-ui       review overlay (JS/CSS)
│   ├── sphinx/          deciwa-sphinx   Sphinx extension
│   ├── client/          @danwos/deciwa-client   engine client for host apps (TypeScript)
│   └── monsterbrain/    deciwa-monsterbrain     the monsterbrain extension
├── docs/                these docs – product, integrations, decisions,
│                        technical details
├── .deciwa/             review data of these docs (config.toml: what must be approved)
├── mockups/             first clickable mock-up of the feedback UI, demo recorder
├── pyproject.toml       the uv workspace (all packages + docs tools)
└── uv.lock

Pakete¶

Die Aufteilung in Pakete ist deciwa ist ein Repository a... (DEC_PACKAGES).

deciwa ist ein Repository mit einem Paket pro Teil – ein uv-Workspace. Alle Pakete teilen sich den Python-Namespace deciwa.

Durchgezogen: was ein Paket importiert. Gestrichelt: wie die Teile beim Review mit Server miteinander sprechen.

Ordner	Distribution	Import	Enthält	Hängt ab von
`packages/core`	`deciwa-core`	`deciwa.core`	Modell, `.deciwa/`-Store, Engine – Zustände, Review-Regeln, Projektüberblick, Export/Import	–
`packages/server`	`deciwa-server`	`deciwa.server`	lokaler Review-Server: liefert eine gebaute Site aus, die JSON-API für die Review-Oberfläche, baut bei Änderungen neu und lädt neu; kennt kein Build-Tool – der Aufrufer übergibt den Build-Befehl	core
`packages/cli`	`deciwa-cli`	`deciwa.cli`	der Befehl `deciwa`; `deciwa serve` übergibt den Sphinx-Build an den Server	core, server
`packages/ui`	`deciwa-ui`	`deciwa.ui`	das Review-Overlay (JavaScript, CSS, Logo) im danwos-Tool-UI-Kit, inklusive der Offline-Engine und des Web-Skripts; Quellen in `js/`, mit `npm run build` nach `static/` gebaut; keine Python-Logik	–
`packages/sphinx`	`deciwa-sphinx`	`deciwa.sphinx`	Sphinx-Erweiterung: findet die Elemente jeder Seite, schreibt den Elemente-Index, liefert die Review-Oberfläche mit	core, ui
`packages/client`	`@danwos/deciwa-client` (npm)	–	findet, startet und prüft die Engine für eine Host-App, typisierte Aufrufe der JSON-API (Host-Apps)	die Engine (`deciwa serve --api-only`)
`packages/monsterbrain`	`deciwa-monsterbrain` (npm, privat)	–	die monsterbrain-Erweiterung: Overlay auf dargestellten Dateien, Seitenpanel, Markierungen im Baum, MCP-Tools; `npm run build` bündelt Client und Overlay nach `dist/`	client, ui

deciwa-sphinx importiert deciwa-server nicht: ein statischer (Offline-)Build braucht keinen Server. Mit deciwa serve führt der Server den Sphinx-Build aus, und die Review-Oberfläche in den Seiten spricht mit der JSON-API des Servers.

Regeln:

Logik lebt nur in deciwa-core. Die Offline-Engine in deciwa-ui spiegelt ihre Regeln für Reviews ohne Server und muss mit ihr Schritt halten.
deciwa-server und deciwa-cli werden von jeder Integration wiederverwendet, die im Browser reviewt oder die CLI aufruft.
Ein Integrationspaket hängt von deciwa-core und, für eine Browser-Oberfläche, von deciwa-ui ab – nie von einer anderen Integration.

Einrichten¶

$ uv sync                          # all packages, editable, plus the docs tools
$ .venv/bin/deciwa serve           # the CLI from packages/cli

deciwa in einem anderen Sphinx-Projekt nutzen:

$ cd ~/workspace/deciwa/packages
$ uv pip install --python <project>/.venv/bin/python -e core -e server -e cli -e ui -e sphinx

Seiten¶

Seite	Entscheidet
Stack	Sprache, Packaging, Tooling
Schichten	Module des Cores und wie sie voneinander abhängen
Adapter	wie ein Format zu Elementen und Selektoren wird
Dateiformat	das JSON in `.deciwa/`
Zustands-Engine	wie der Zustand eines Elements berechnet wird
CLI	Befehle, Adressierung von Elementen, JSON-Ausgabe
Skills	was die zwei Agent-Skills tun und wie sie ausgeliefert werden
Einführung	wie 0.1 in Daniels Wissensbasis kommt
An deciwa arbeiten	Docs als Wahrheit, sie in deciwa reviewen, vom Vorschlag zur Entscheidung

Alle Vorschläge¶

ID	Title	Status	page
PROP_ADAPTER_API	Eine kleine Adapter-Schnittstelle für alle Formate	draft	technical/adapters
PROP_ANNOTATION	Aufbau einer Annotation	draft	technical/file-format
PROP_CLI_CHECK	deciwa status kann einen CI-Lauf bei Einfrier-Alarmen scheitern lassen	draft	technical/cli
PROP_CLI_COMMANDS	Befehle in 0.1	draft	technical/cli
PROP_CLI_JSON	JSON-Ausgaben haben für jeden Befehl dieselbe Hülle	draft	technical/cli
PROP_DOCS_REVIEW_SOURCE	Reviews und Entscheidungen finden nur auf den englischen Docs statt	draft	technical/working
PROP_DOCS_TRANSLATION	Englisch ist die Quelle der Docs; Deutsch ist eine Übersetzung in gettext-Katalogen	draft	technical/working
PROP_DOM_ADAPTER	Das Web-Skript findet die Elemente einer gerenderten Seite selbst	draft	technical/adapters
PROP_ENGINE_BINARY	Die Engine wird mit PyInstaller gebaut, ein Ordner pro Plattform	draft	technical/hosts
PROP_FILE_LAYOUT	Eine Annotationsdatei pro Quelle, deterministisches JSON	draft	technical/file-format
PROP_FINGERPRINT	Der Fingerprint umfasst den Quelltext mit normalisierten Leerzeichen	draft	technical/state-engine
PROP_FREE_TEXT	Eine freie Textauswahl ist ein Textzitat innerhalb ihres nächsten Elements	draft	technical/adapters
PROP_LATEST_WINS	Solange ein Element unverändert ist, ersetzen das neueste Urteil und die neueste Bewertung einer Person die früheren	draft	technical/file-format
PROP_LAYERS	Der Core ist in Schichten mit strenger Abhängigkeitsrichtung aufgeteilt	draft	technical/layers
PROP_OVERLAY_PARTS	Das Overlay ist aufgeteilt in Elementquelle, Speicher und Oberfläche	draft	technical/web
PROP_PYTHON_CORE	Core und CLI sind in Python geschrieben	draft	technical/stack
PROP_RESOLVE	Selektoren werden in fester Reihenfolge probiert, und der erste eindeutige Treffer gewinnt	draft	technical/state-engine
PROP_ROLLOUT_LOCATION	.deciwa/ im Wurzelverzeichnis der Wissensbasis, committet	draft	technical/rollout
PROP_ROLLOUT_MIGRATE	Bestehende [CHECK]-Markierungen werden einmalig in Anfragen überführt	draft	technical/rollout
PROP_RST_DOCUTILS	Der rST-Adapter parst mit docutils, ohne Sphinx auszuführen	draft	technical/adapters
PROP_SCHEMA	Ein JSON Schema ist der dokumentierte Vertrag	draft	technical/file-format
PROP_SELECTORS	Element-Selektoren sind Pfade aus Überschriften plus ein Zähler pro Abschnitt	draft	technical/adapters
PROP_SKILLS_FORMAT	Zwei Skills im Agent-Skills-Format, im Repository mitgeliefert	draft	technical/skills
PROP_SNAPSHOT	Der Schnappschuss des Elementtexts wird mit jeder Annotation gespeichert	draft	technical/file-format
PROP_STATE_RULES	Zustandsregeln in dieser Reihenfolge	draft	technical/state-engine
PROP_TOOLING	Tooling: Python 3.12+, uv, ruff, pytest, click	draft	technical/stack
PROP_VSCODE_PLATFORM	VS Code bekommt ein Paket pro Plattform mit der Engine darin	draft	technical/hosts
PROP_WEB_BUNDLE	Ein Bundle, gebaut mit esbuild, die Oberfläche in einem Shadow DOM	draft	technical/web
PROP_WEB_FILES	Webseiten ohne Quelldatei werden unter ihrer Adresse gespeichert	draft	technical/file-format
PROP_WEB_HOSTING	Das Web-Skript wird mit der Doku unter einem versionierten Pfad gehostet	approved	technical/web
PROP_WEB_INDEX	Der Browser merkt sich die Elemente jeder besuchten Seite	draft	technical/web
PROP_WEB_ONE_LINE	Das Skript zu laden genügt – deciwa erscheint immer	approved	technical/web
PROP_WEB_RESCAN	Seiten, die sich nach dem Laden ändern, werden erneut gescannt	draft	technical/web
PROP_WEB_SOURCE	Eine Seite wird erkannt an ihrem Meta-Tag, einer Zuordnungsregel oder ihrer Adresse	approved	technical/web

Wie die Vorschläge mit den Entscheidungen zusammenhängen¶