From a9fce06963fcaca2f5979b5b397770ebe30c360a Mon Sep 17 00:00:00 2001 From: Cuarroc <47299143+Cuarroc@users.noreply.github.com> Date: Sat, 3 Oct 2026 22:34:31 +0200 Subject: [PATCH 1/2] docs: state HQ proof boundaries for W3-08 and consumers Add the installed-build proof path (running executable, HQ v1, manifest.state matched at the build commit) to ci-lokal.md and the limits of runtime/context/cursor queries to the dev-hq README. Proposed commands are instructions for a later proof, not observations. No-Test: pure documentation Co-Authored-By: Claude Sonnet 5.5 --- docs/ci-lokal.md | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/dev-hq/README.md | 25 +++++++++++++++++++++++++ 2 files changed, 68 insertions(+) diff --git a/docs/ci-lokal.md b/docs/ci-lokal.md index 8c47d619..af25306c 100644 --- a/docs/ci-lokal.md +++ b/docs/ci-lokal.md @@ -136,6 +136,49 @@ Der Release-*Build* selbst ist lokal machbar (`npx tauri build`, `release.yml`; es nach `scripts/` auszulagern ist ein offener Punkt (in dieser Umgebung stand kein pwsh zur Verfügung, um die Auslagerung zu belegen). +## Was „grün" für W3-08 nicht belegt: der installierte HQ-v1-Stand + +Die Gates oben belegen den **Quelltext**. Ob die *tatsächlich laufende, +installierte* App HQ v1 spricht, ist eine andere Frage (Paket W3-08 in +`docs/PLAN.md`, Stand: offen). Quelle, Installer-Inhalt oder Konfiguration +allein schließen sie nicht — W3-08 gilt aus diesen Quellen nie als erledigt. + +Der spätere Beleg braucht alle vier Teile zugleich: + +1. **Welche Datei läuft wirklich?** Die tatsächlich laufende, installierte + ausführbare Datei, samt Bindung an das Artefakt bzw. den Build-Commit. +2. **HQ v1 antwortet.** Das Control-API der laufenden App ist erreichbar und + spricht HQ v1. +3. **`manifest.state == matched`**, ausdrücklich — gegen den Checkout *an + diesem Build-Commit*. Der Befehl vergleicht den SHA-256 der eingebetteten + `agent-defaults.json` (LF-normalisiert) mit dem der Laufzeit. +4. Alle drei beziehen sich auf **denselben** Build. + +Befehle für diesen späteren Beleg (nur lesend; hier **nicht** ausgeführt, die +App wird dafür nicht gestartet — das sind Anweisungen, keine Beobachtungen): + +```sh +npm run dev:doctor -- --json # ohne --apply; Zeile "runtime" lesen +pa hq runtime # profilesPath, capabilities, manifestFingerprint +``` + +Fallstricke, jeweils belegt durch den Quelltext: + +- `runtime.state: ok` kann mit `manifest.state: unavailable` zusammen + auftreten (kein Vergleichswert). Erreichbarkeit („runtime bereit") ist daher + **kein** Beleg; verlangt wird `matched`, nicht bloß „ok". +- Das Manifest ist ein Fingerabdruck der *ausgelieferten Standardprofile*. Es + ist keine Anbieter-Bestätigung und sagt nichts über Modell, Effort oder + Zugangsdaten. +- Das Manifest des `native-package` ist etwas anderes: die signierte + Nutzlast-Identität von `native-capture`, nicht die HQ-`agent-defaults`. +- Eine MSI-Inventur mit `installed: false` / `payloadBytesVerified: false` + belegt nur die Dateitabelle. MSI-Hash und Exe-Hash sind verschiedene Objekte; + dass beide existieren (oder eine Reparatur lief), ist keine Bindung. +- Die Bahn öffnet keine neue Voraussetzung: kein Produktions-Signing (R-1). + Der Produktionsschlüssel (W3-07) bleibt eine spätere Entscheidung des + Nutzers; Installieren und Release sind je eine eigene Nutzerentscheidung. + ## Wenn ein Gate rot ist `gates.sh` bricht wie ein CI-Schritt beim ersten roten Gate ab, nennt den diff --git a/docs/dev-hq/README.md b/docs/dev-hq/README.md index e6b12a66..e1a0f64c 100644 --- a/docs/dev-hq/README.md +++ b/docs/dev-hq/README.md @@ -62,6 +62,31 @@ readiness marker). An unrelated id gets the cautious defaults. The optional fields. Enable/disable stays with the desktop app's settings — the HQ proxy deliberately does not write the live database. +## What the agent-facing HQ queries do and do not prove + +Consumers are `pa hq runtime`, `pa hq context --project ` and the +changes-only cursor pages (`pa hq changes --project `). Read their output +within these limits: + +- **`pa hq runtime`** reports the profiles and capabilities as *configured*. + Its compiled-default `manifestFingerprint` is a valid, limited byte + fingerprint of the shipped `agent-defaults.json` (LF-normalised SHA-256). It + is not proof of the whole Git SHA, the model, the effort or any credential, + and not a provider attestation. Comparing it with the local checkout is the + `manifest` row of `npm run dev:doctor -- --json`; the full installed-build + proof path is in `docs/ci-lokal.md` (W3-08). +- **`pa hq context --project `** and the cursor pages answer a + project-filtered query. Do not infer credential scope from the project + filter; this document makes no claim about a RunCredential context + permission (`agent_access` was not read). +- **Freshness.** `snapshot.commit` and `snapshot.run` may be `null`. + `snapshot.sourceTimestamp` can be the journal or read time (a fallback), so + a timestamp alone does not prove a fresh checkout. +- **Cursors.** A future cursor, or an empty page with `hasMore: false`, does + not by itself prove the journal head or epoch. +- **Host numbers.** `HostAdmission.activeClaims` and the memory figures are + host-wide, not per project. + ## Setup helper The Live view opens with a **Setup helper** that checks this machine: Node, From 0b59019c8f970c4edfe8942fce8573df83b47c8f Mon Sep 17 00:00:00 2001 From: Cuarroc <47299143+Cuarroc@users.noreply.github.com> Date: Sat, 3 Oct 2026 22:54:55 +0200 Subject: [PATCH 2/2] docs: name the runtime manifest fingerprint field correctly Replace the non-existent manifestFingerprint with the real provenance.builtinManifestSha256 field in the dev-hq README and the ci-lokal example comment. Pure documentation; no code changes. No-Test: pure documentation Co-Authored-By: Claude Sonnet 5.5 --- docs/ci-lokal.md | 2 +- docs/dev-hq/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ci-lokal.md b/docs/ci-lokal.md index af25306c..a1ecf3c3 100644 --- a/docs/ci-lokal.md +++ b/docs/ci-lokal.md @@ -159,7 +159,7 @@ App wird dafür nicht gestartet — das sind Anweisungen, keine Beobachtungen): ```sh npm run dev:doctor -- --json # ohne --apply; Zeile "runtime" lesen -pa hq runtime # profilesPath, capabilities, manifestFingerprint +pa hq runtime # profilesPath, capabilities, provenance.builtinManifestSha256 ``` Fallstricke, jeweils belegt durch den Quelltext: diff --git a/docs/dev-hq/README.md b/docs/dev-hq/README.md index e1a0f64c..b5155f16 100644 --- a/docs/dev-hq/README.md +++ b/docs/dev-hq/README.md @@ -69,7 +69,7 @@ changes-only cursor pages (`pa hq changes --project `). Read their output within these limits: - **`pa hq runtime`** reports the profiles and capabilities as *configured*. - Its compiled-default `manifestFingerprint` is a valid, limited byte + Its compiled-default `provenance.builtinManifestSha256` is a valid, limited byte fingerprint of the shipped `agent-defaults.json` (LF-normalised SHA-256). It is not proof of the whole Git SHA, the model, the effort or any credential, and not a provider attestation. Comparing it with the local checkout is the