Dateiformat

Status: Entwurf

Vorschläge von Claude – nicht verbindlich, bis Daniel sie freigibt.

.deciwa/
├── config.toml                          optional settings
└── annotations/
    ├── 20_facts/company/founder.md.json one file per annotated source
    └── _web/danwos.dev/services.json    web pages without a mapped source
.deciwa/web-pages.json                   elements of the imported web pages

Vorschlag: Eine Annotationsdatei pro Quelle, deterministisches JSON PROP_FILE_LAYOUT

status: draft refines: DEC_DECIWA_FOLDER, DEC_GIT_COMMITTED refined by: PROP_WEB_FILES

Der Pfad unter annotations/ spiegelt den Quellpfad relativ zu dem Ordner, der .deciwa/ enthält. Die CLI schreibt sortierte Schlüssel, zwei Leerzeichen Einrückung, eine Annotation nach der anderen nach Erstellungszeit und einen abschließenden Zeilenumbruch – so bleiben Git-Diffs klein und Merge-Konflikte selten.

Vorschlag: Aufbau einer Annotation PROP_ANNOTATION

status: draft refines: DEC_FREEZE, DEC_THREE_MODES, DEC_VERDICTS refined by: PROP_LATEST_WINS, PROP_SNAPSHOT

{
  "deciwa": "0.1",
  "source": "20_facts/company/founder.md",
  "annotations": [
    {
      "id": "k7q2m9xa",
      "kind": "feedback",
      "target": {
        "selectors": [
          {"type": "structural", "value": "md:paragraph:Career/Advisor#1"},
          {"type": "TextQuoteSelector", "exact": "advisor since October 2026",
           "prefix": "Daniel works as ", "suffix": "."},
          {"type": "TextPositionSelector", "start": 1204, "end": 1230}
        ],
        "fingerprint": "sha256:9c1e…",
        "snapshot": "Daniel works as advisor since October 2026."
      },
      "author": "daniel",
      "created": "2026-10-19T10:12:00Z",
      "verdict": "rephrase",
      "comment": "too stiff, say it like a person",
      "status": "open",
      "replies": []
    }
  ]
}

Feld	Werte	Hinweis
kind	feedback · rating · request	die drei Arbeitsweisen bleiben auch in den Daten getrennt
verdict	approve · reject · freeze · delete · note	nur für feedback; note = ein Kommentar ohne Urteil
stars	0–5	nur für rating
question, to	Text, Liste von Autoren	nur für request; Antworten sind replies mit optionalem verdict
snapshot	Text des Elements, als die Annotation erstellt wurde	nötig für deciwa diff, Ansichten veralteter Elemente und den Einfrier-Alarm
status	open · resolved	Aufgaben starten open: löschen, ablehnen, Notiz (ein Kommentar für die KI) und Anfragen; Freigaben, Einfrierungen und Bewertungen starten resolved
author	daniel, agent:claude	aus git config user.email oder DECIWA_AUTHOR
id	8 Zeichen, Base32 in Kleinbuchstaben, zufällig	kurz genug, um es in der CLI zu tippen

Vorschlag: Solange ein Element unverändert ist, ersetzen das neueste Urteil und die neueste Bewertung einer Person die früheren PROP_LATEST_WINS

status: draft refines: DEC_THREE_MODES, PROP_ANNOTATION

Ein Fehlklick oder ein zweiter Gedanke darf keine Einträge anhäufen. Solange der Fingerprint des Elements gleich ist, ersetzt ein neues Urteil derselben Person das alte Urteil und eine neue Bewertung die alte Bewertung. Hat sich das Element geändert, bleiben frühere Annotationen als Verlauf erhalten (so funktioniert stale). Notizen und Fragen werden nie ersetzt; ein Kommentar, der mit einem ersetzten Urteil kam, bleibt als Notiz erhalten. So endet auch ein Einfrieren: die Person gibt ein anderes Urteil ab (Ein Einfrieren endet mit ei... (DEC_FREEZE_BY_VERDICT)).

Vorschlag: Der Schnappschuss des Elementtexts wird mit jeder Annotation gespeichert PROP_SNAPSHOT

status: draft refines: PROP_ANNOTATION

Ohne ihn kann deciwa sagen, dass sich ein freigegebener oder eingefrorener Text geändert hat, aber nicht, wie er aussah – und der Einfrier-Alarm muss die alte Formulierung zeigen (Neues Urteil: einfrieren (DEC_FREEZE)). Der Preis ist etwas doppelter Text in .deciwa/.

Vorschlag: Ein JSON Schema ist der dokumentierte Vertrag PROP_SCHEMA

status: draft refines: DEC_CLI_MASTER

schema/deciwa-0.1.schema.json wird mit der CLI und in diesen Docs veröffentlicht. Die CLI validiert jede Datei, die sie liest. Ein neues Hauptfeld bedeutet eine neue Schemaversion; die CLI liest ältere Versionen und schreibt die neueste.

config.toml

author = "daniel"                 # overrides git config

[adapters]
"**/*.md"  = "md"
"**/*.rst" = "rst"
"**/*.txt" = "text"

[needs]
directives = ["req", "spec", "dec", "prop", "question"]

[ignore]
paths = ["90_archive/**", "_build/**"]

Web-Quellen

Vorschlag: Webseiten ohne Quelldatei werden unter ihrer Adresse gespeichert PROP_WEB_FILES

status: draft refines: PROP_FILE_LAYOUT, PROP_WEB_SOURCE

Eine mit dem Web-Skript reviewte Seite, deren Quelle der Fallback web:<host><path> ist, wird als annotations/_web/<host>/<path>.json gespeichert; der Pfad / wird zu index, ein Port wird als _<port> geschrieben, und die Datei behält die Adresse in ihrem Feld source. deciwa import wendet zuerst die Regeln von [web] an: eine Regel zählt nur, wenn ihre Datei existiert, also landen zugeordnete Seiten in der Datei ihrer Quelle und alles andere behält seine Adresse. Kommt später eine Regel dazu, verschiebt deciwa remap die Annotationen aus _web/ in ihre Quelldateien. Ein Export aus dem Web-Skript trägt die Elemente seiner Seiten mit (Selektor, Art, Label, Text, Fingerprint). Der Import legt sie nach Adresse in .deciwa/web-pages.json ab, damit todo, show und status funktionieren, ohne in Python HTML zu parsen; die Selektoren bleiben html:…, auch bei Seiten, die einer Markdown-Datei zugeordnet sind. Ein solcher Import ersetzt nur die Review-Daten der Seiten in der Datei, nie den Rest des Projekts.

[web]
site = "danwos.dev"                                   # optional, the host of the pages
sources = [                                           # optional, first match wins
  { url = "/",       file = "src/content/pages/index.md" },
  { url = "/blog/*", file = "src/content/blog/*.md" },
  { url = "/*",      file = "src/content/pages/*.md" },
]

Ohne [web] – oder ganz ohne .deciwa/, wenn nur der Browser genutzt wird – behält jede Seite ihre Adresse. site beschränkt die Regeln auf Seiten dieses Hosts; ohne gelten sie für jeden Host, auch localhost beim Entwickeln. Ein Stern in url steht für einen oder mehrere Teile der Adresse und ersetzt die Sterne in file in derselben Reihenfolge.