@hybridlabor-api/aos 4.6.6 → 4.7.1

package/docs/AUDIT_BRIEF_ECC_STORE.md

@@ -0,0 +1,122 @@
+# Audit Brief: AOS Skill, Subagent & Extras Store (ECC Fork Integration)
+
+**Datum:** 2026-09-24  
+**Projekt:** `@hybridlabor-api/aos` (AOS — Curated AI Agent OS)  
+**Dokumenttyp:** Architektur- & Sicherheits-Audit-Briefing für externe Reviewer- / Auditor-Agenten  
+**Status:** Vor Implementierung (Architektur-Review)
+
+---
+
+## 1. Executive Summary & Zielsetzung
+
+AOS (`@hybridlabor-api/aos`) ist ein multi-harness Agenten-Betriebssystem für autonome Coding-Pipelines (unterstützt Claude Code, Google Antigravity, Codex, Cursor, Roo Code und OpenCode). Aktuell liefert AOS ca. 185 kuratierte Kern-Skills und eine 7-Node-Graph-Architektur mit deterministischen Übergängen (Architect → TechLead → Build → Reviewer → Shipping).
+
+### Geplante Erweiterung
+Aufbau eines dezentralen **Skill-, Subagent- und Extras-Stores** als Fallback-Ebene auf Basis eines gepflegten Forks von **[affaan-m/ECC](https://github.com/affaan-m/ECC)** (Everything Claude Code, MIT-Lizenz):
+1. **Fallback in `/ask-tim`:** Wenn ein Nutzer nach einer Domäne oder einem Framework sucht (z. B. Spring Boot, Godot, Django), das nicht im 185-Skill-Kern von AOS liegt, soll `/ask-tim` automatisch passende Erweiterungen aus dem Store vorschlagen.
+2. **Fallback in `--skill=<name>`:** Bei Pipeline-Aufrufen wie `/startcycle-graph --skill=django-pro "Ziel"` soll ein lokal fehlender Skill nicht sofort hart mit einer Eskalation abbrechen, sondern im Store gesucht, validiert und on-demand geladen werden.
+3. **Subagent & Extras Katalog:** Bereitstellung von spezialisierten Auxiliary Agents, Templates, Rules und Hooks aus dem ECC-Ökosystem als modulare AOS-Erweiterungen.
+
+---
+
+## 2. Aktueller Systembestand in AOS (Ist-Zustand)
+
+### 2.1 Relevante Code- & Konfigurations-Pfade
+- **Multi-Harness Installer:** [`installer.js`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/installer.js) — Synchronisiert Skills, MCP-Configs und Agents nach `~/.claude/`, `~/.agents/`, `~/.codex/`, `~/.cursor/` etc.
+- **Pipeline Dispatcher:** [`.claude/workflows/startcycle-dispatch.mjs`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/.claude/workflows/startcycle-dispatch.mjs) — Verwaltet den Startcycle-Graph, GO-Gates, mandatory skills (`--skill=<name>`) und Agenten-Orchestrierung.
+- **Skill Router:** [`skills/global_config/ask-tim/SKILL.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/skills/global_config/ask-tim/SKILL.md) — Zentraler Einstiegspunkt für Intent-Erkennung und Skill-Auswahl.
+- **Vendor Tracking:** [`~/.agents/vendor-manifest.json`](file:///Users/timrennings/.agents/vendor-manifest.json) — Pinned Git SHAs für Upstream-Repositories (z. B. `anti-slop`, `skylos`, `claude-red`).
+- **Bereits portierte ECC-Komponenten:** [`THIRD_PARTY_NOTICES.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/THIRD_PARTY_NOTICES.md) — 6 Auxiliary Agents (`silent-failure-hunter`, `security-reviewer`, `go-build-resolver`, `database-reviewer`, `opensource-forker`, `opensource-sanitizer`) und `plan-canvas`.
+
+### 2.2 Bestehende `--skill` Validierungslogik (`startcycle-dispatch.mjs:701-741`)
+```javascript
+// Aktuelles Verhalten:
+if (mandatorySkillNames.length > 0) {
+  const skillCheckResult = await agent(`Check whether each of these skill names resolves to an installed skill...`);
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    // HARTES ESKALIEREN:
+    return await escalate(`--skill named skill(s) that could not be found: ${missing.join(', ')}...`);
+  }
+}
+```
+
+---
+
+## 3. Geplante Soll-Architektur
+
+```mermaid
+flowchart TD
+    User([Nutzer-Anfrage / Prompt]) --> Trigger{Einstiegspunkt}
+    
+    Trigger -->|1. /ask-tim Suche| AskTim[ask-tim Router]
+    Trigger -->|2. --skill=name Flag| Dispatcher[startcycle-dispatch]
+    
+    AskTim --> CheckCore1{Im 185-Skill AOS Core?}
+    Dispatcher --> CheckCore2{Lokal auf Disk installiert?}
+    
+    CheckCore1 -->|Ja| UseCore[Empfehle/Nutze nativen AOS-Skill]
+    CheckCore2 -->|Ja| RunCore[Starte Pipeline mit Core-Skill]
+    
+    CheckCore1 -->|Nein| QueryStore[Abfrage lokaler ecc-store-index.json]
+    CheckCore2 -->|Nein| QueryStore
+    
+    QueryStore --> MatchFound{Match im Store?}
+    MatchFound -->|Nein| FinalEscalate[Eskalation / Keine Treffer]
+    MatchFound -->|Ja| StoreAction{Aktion}
+    
+    StoreAction -->|bei /ask-tim| ShowOption[Empfehlung + 'aos store install <name>']
+    StoreAction -->|bei --skill| GateCheck[GO-Gate / Confirmation]
+    
+    GateCheck -->|Genehmigt| FetchEngine[On-Demand Sync in ~/.agents/skills/]
+    FetchEngine --> ValidateHarness[POSIX & Harness-Tool Linter]
+    ValidateHarness --> RunPipeline[Pipeline-Start ohne Unterbrechung]
+```
+
+---
+
+## 4. Kernfragen & Prüffelder für das Audit
+
+Der Auditor-Agent wird gebeten, folgende kritische Fragestellungen strukturiert zu beleuchten:
+
+### 1. GO-Gate & Sicherheit (Supply-Chain-Risiko)
+* **Problem:** Dürfen externe Skills oder Agents während eines autonomen Pipeline-Laufs dynamisch aus einem Remote-Repository nachgeladen werden?
+* **Audit-Frage:** Wie muss die Bestätigung strukturiert sein, damit die strikte AOS-Regel (*"read-only until literal GO"*) nicht kompromittiert wird? Genügt ein lokales, kryptografisch verifiziertes Manifest mit SHA-256 Checksummen?
+
+### 2. Multi-Harness Tool-Inkompatibilitäten
+* **Problem:** `affaan-m/ECC` ist primär für Claude Code konzipiert und verwendet teils hardcodierte Tool-Namen wie `Bash`, `View`, `Edit`, `GlobTool`.
+* **Audit-Frage:** Welche automatisierten Transformations- oder Linter-Regeln müssen beim Ingest/Installationsschritt greifen, damit importierte Skills fehlerfrei in Google Antigravity (`run_command`, `view_file`), OpenAI Codex (`exec`, `read_file`) und Cursor funktionieren?
+
+### 3. Context Window & Token-Budget
+* **Problem:** Ein ungefilterter Import von 400+ Skills würde die Context-Limits und System-Prompts überlasten.
+* **Audit-Frage:** Ist die gewählte Architektur mit einem leichtgewichtigen, lokalen Vektor- oder Metadaten-Index (`ecc-store-index.json` < 100 KB) optimal, und wie sollte das semantische Ranking bei ungenauen Begriffen erfolgen?
+
+### 4. Namenskonflikte & Rangfolge (Precedence)
+* **Problem:** Was passiert, wenn ein ECC-Skill denselben Namen trägt wie ein existierender oder zukünftiger AOS-Kern-Skill (z. B. `tailwind-patterns` oder `tdd-workflow`)?
+* **Audit-Frage:** Sollte ein striktes Namespacing (`ecc/<skill-name>` oder Tagging `origin: ecc`) erzwungen werden, um Overwrites und Seiteneffekte auszuschließen?
+
+### 5. Wartungs- und Sync-Strategie des Forks
+* **Problem:** ECC wird kontinuierlich weiterentwickelt.
+* **Audit-Frage:** Wie sieht eine nachhaltige GitHub-Action-Sync-Pipeline für den Fork `hybridlabor-api/ECC` aus, die neue Upstream-Releases verarbeitet, ohne manuell angepasste Harness-Kompatibilitäts-Fixes zu überschreiben?
+
+---
+
+## 5. Referenzierte Komponenten & Schnittstellen
+
+| Komponente | Datei / Pfad | Relevante Zeilen / Kontext |
+|---|---|---|
+| **Pipeline-Dispatcher** | [`.claude/workflows/startcycle-dispatch.mjs`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/.claude/workflows/startcycle-dispatch.mjs) | Z. 701–741 (Mandatory Skill Check & Eskalation) |
+| **Skill Router** | [`skills/global_config/ask-tim/SKILL.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/skills/global_config/ask-tim/SKILL.md) | Z. 1–70 (Main Flow & Intent Index) |
+| **Vendor Registry** | [`~/.agents/vendor-manifest.json`](file:///Users/timrennings/.agents/vendor-manifest.json) | Vorhandene Pinned-Upstream-Repositories |
+| **Lizenz- & Provenance** | [`THIRD_PARTY_NOTICES.md`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/THIRD_PARTY_NOTICES.md) | Z. 12–50 (Bisheriger Port von ECC-Agents) |
+| **AOS Installer & Sync** | [`installer.js`](file:///Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills/installer.js) | Z. 110–135 (Multi-Platform Fan-out) |
+
+---
+
+## 6. Erwartetes Audit-Ergebnis
+
+Der externe Auditor-Agent sollte am Ende einen Bericht mit folgendem Schema abliefern:
+1. **Architektur-Bewertung:** Bestätigung oder Korrektur der vorgeschlagenen Store- und Fallback-Architektur.
+2. **Identifizierte Risiken:** Kategorisiert nach *Blocker*, *Warnung*, *Empfehlung*.
+3. **Konkrete Lösungsvorschläge:** Für Tool-Mapping, Token-Schonung und GO-Gate-Integration.
+4. **Sign-Off / Freigabe-Empfehlung:** Für den Start der Implementierung von Phase 1.

package/docs/PLAN_AOS_STORE_PHASE1.md

@@ -0,0 +1,190 @@
+# Execution Plan: AOS Skill, Subagent & Extras Store (Phase 1)
+
+**Target Repository:** `/Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills`  
+**Target Worktree:** `/Users/timrennings/dev/bdb-dev/aos-wt-store`  
+**Branch:** `feat/aos-store` (branched from `main`)  
+**Scope:** Phase 1 — Core Store Infrastructure, Offline Index, CLI, and Dispatcher Fallback  
+**Audience:** Autonomous Implementation Agent  
+**Upstream Source:** `https://github.com/affaan-m/ECC` (Pinned Commit, MIT License)
+
+---
+
+## 🎯 1. Mission & Architectural Invariants
+
+You are implementing Phase 1 of the **AOS Store** (`@hybridlabor-api/aos`). This provides an on-demand fallback layer for skills and subagents sourced from `affaan-m/ECC` whenever a requested capability is not in AOS's 185-skill core.
+
+### ⚠️ Non-Negotiable Invariants (Audit-Mandated)
+1. **No Forks:** Do NOT fork ECC to GitHub. Pin `affaan-m/ECC` directly via Git SHA in `vendor-manifest.json` (identical to `anti-slop` and `skylos`).
+2. **No Mid-Run Downloads:** Never download or prompt to download during a `/startcycle-graph` run (violates the GO-Gate and headless guarantees). If `--skill=<name>` is missing, the dispatcher must escalate with a clear manual install instruction:
+   ```text
+   "<name> is not installed. Found in the ECC store.
+   Run: aos store install <name>
+   Then re-run your startcycle command."
+   ```
+3. **No File System in Dispatcher:** `.claude/workflows/startcycle-dispatch.mjs` has no direct `fs` access. The mandatory skill check is an `agent()` call (Haiku); you must extend its JSON schema with `store_matches: string[]` instead of adding `fs` calls.
+4. **Trust Anchor is AOS Package:** `lib/ecc-store-index.json` ships inside the `@hybridlabor-api/aos` npm package. Downloads from GitHub must match the SHA-256 hash in this index. Hash mismatch = hard failure.
+5. **Phase-1 Scope: Markdown Only:**
+   - Only import `skills/` and `agents/` (Subagents).
+   - **Strictly exclude** `scripts/`, `hooks/`, and `rules/` (prevents RCE and config pollution).
+6. **Collision Invariant:** AOS core skills ALWAYS take precedence. If an ECC skill shares a name with an existing AOS skill, it is skipped and logged.
+7. **Future-Proofing for Fucksaas & AO:** Every store item must contain schema fields for `tier: "free"`, `requires_auth: false`, and `origin: "ecc"` so Fucksaas PRO pay-gates and AO marketplace UI can be layered on in Phase 2 without changing the schema.
+
+---
+
+## 🛠️ 2. Worktree Initialization
+
+Execute the following commands to create and enter the isolated worktree:
+
+```bash
+cd /Users/timrennings/dev/bdb-dev/bdb-dev-optimized-agent-skills
+git fetch origin main
+git worktree add -b feat/aos-store /Users/timrennings/dev/bdb-dev/aos-wt-store main
+cd /Users/timrennings/dev/bdb-dev/aos-wt-store
+```
+
+All modifications below MUST take place inside `/Users/timrennings/dev/bdb-dev/aos-wt-store/`.
+
+---
+
+## 📋 3. Step-by-Step Implementation Checklist
+
+### Step 1: Upstream Pinning & Provenance
+- [ ] Inspect the latest stable commit SHA of `affaan-m/ECC`:
+  ```bash
+  gh api repos/affaan-m/ECC/commits/main --jq '.sha'
+  ```
+- [ ] Add `ecc-store` entry to `vendor-manifest.json`:
+  ```json
+  "ecc-store": {
+    "upstream": "https://github.com/affaan-m/ECC",
+    "pinned_commit": "<FULL_SHA>",
+    "purpose": "On-demand fallback store for skills and auxiliary subagents",
+    "target": "lib/ecc-store-index.json"
+  }
+  ```
+- [ ] Update `THIRD_PARTY_NOTICES.md` to document the full scope of ECC components and MIT license terms.
+
+### Step 2: Store Index Generator (`scripts/build-ecc-store-index.mjs`)
+- [ ] Create `scripts/build-ecc-store-index.mjs`. The script must:
+  1. Fetch the tree from GitHub API for the pinned commit (`repos/affaan-m/ECC/git/trees/<sha>?recursive=1`) or clone to a temporary cache.
+  2. Filter strictly for Markdown:
+     - `skills/**/SKILL.md` or `skills/**/*.md`
+     - `agents/*.md`
+  3. Validate & sanitize frontmatter:
+     - Must conform to AOS standards (runnable through `scripts/validate-skills.mjs` rules).
+     - Compute SHA-256 for each raw file.
+     - Scan for forbidden tokens (hardcoded Claude-only tools like `Bash`, `View`; replace or flag compatibility).
+  4. Build schema:
+     ```typescript
+     interface StoreIndex {
+       version: "1.0.0";
+       generated_at: string;
+       pinned_commit: string;
+       skills: Record<string, {
+         name: string;
+         description: string;
+         category: string;
+         tier: "free";
+         origin: "ecc";
+         requires_auth: false;
+         sha256: string;
+         upstream_path: string;
+         harness_support: ("claude" | "antigravity" | "codex" | "cursor" | "roo")[];
+       }>;
+       subagents: Record<string, {
+         name: string;
+         description: string;
+         role: string;
+         tier: "free";
+         origin: "ecc";
+         sha256: string;
+         upstream_path: string;
+       }>;
+     }
+     ```
+  5. Check collisions against local `skills/` in AOS. Any collision is skipped.
+  6. Output the compiled index to `lib/ecc-store-index.json` (keep size under 100 KB).
+- [ ] Run `node scripts/build-ecc-store-index.mjs` and verify `lib/ecc-store-index.json`.
+
+### Step 3: CLI Implementation (`bin/aos-store.mjs` & `installer.js`)
+- [ ] Create `bin/aos-store.mjs`:
+  - `aos store list [--type=skills|agents]` -> Formatted table of available items.
+  - `aos store search <query>` -> Search by name, tags, description in `lib/ecc-store-index.json`.
+  - `aos store install <name> [--project]` ->
+    1. Look up `<name>` in `lib/ecc-store-index.json`.
+    2. Check if already installed locally; collision guard against AOS core.
+    3. Download raw content from `https://raw.githubusercontent.com/affaan-m/ECC/<pinned_sha>/<upstream_path>`.
+    4. Compute SHA-256 and assert match with index (halt on mismatch).
+    5. Write file:
+       - If `--project`: write to `./skills/<name>/SKILL.md`.
+       - If global: fan-out to all active harnesses (`~/.agents/skills/<name>/SKILL.md`, `~/.claude/skills/<name>/SKILL.md`, etc., reusing logic from `installer.js`).
+    6. Log success with green checkmark.
+- [ ] Make `bin/aos-store.mjs` executable (`chmod +x bin/aos-store.mjs`).
+- [ ] Register in `package.json`:
+  ```json
+  "bin": {
+    ...
+    "aos-store": "bin/aos-store.mjs"
+  }
+  ```
+- [ ] Wire up `aos store <args>` in `installer.js` so running `aos store search` forwards directly to `bin/aos-store.mjs`.
+
+### Step 4: Dispatcher Hook (`.claude/workflows/startcycle-dispatch.mjs`)
+- [ ] Locate the `validate-mandatory-skills` agent call around lines 701–741.
+- [ ] Update the prompt and JSON schema:
+  - Add `store_matches: { type: 'array', items: { type: 'string' } }` to the output schema.
+  - Instruct the agent to check `lib/ecc-store-index.json` for any skill not found locally on disk.
+- [ ] Update escalation handling (lines 728–739):
+  ```javascript
+  const missing = skillCheckResult?.missing ?? [];
+  if (missing.length > 0) {
+    const storeMatches = skillCheckResult?.store_matches ?? [];
+    const suggestions = skillCheckResult?.suggestions ?? [];
+    
+    let msg = `--skill named skill(s) that are not currently installed: ${missing.join(', ')}.\n`;
+    if (storeMatches.length > 0) {
+      msg += `Found in the AOS / ECC Store: ${storeMatches.join(', ')}.\n` +
+             `Run: aos store install ${storeMatches.join(' ')}\n` +
+             `Then re-run your startcycle command.\n`;
+    } else if (suggestions.length > 0) {
+      msg += `Did you mean: ${suggestions.join(', ')}?\n`;
+    }
+    return await escalate(msg);
+  }
+  ```
+
+### Step 5: Router Update (`skills/global_config/ask-tim/SKILL.md`)
+- [ ] Add a new section in `ask-tim/SKILL.md` titled `## Outside the core: the ECC store`:
+  - Explain that when no native AOS skill fits (e.g. Django, Spring, Godot), the user can query the store via `aos store search <query>`.
+  - Document `aos store install <name>` for on-demand activation.
+  - Reiterate that the core remains 185 high-trust skills.
+
+### Step 6: Verification & Quality Gate
+- [ ] Run skill validator:
+  ```bash
+  npm run test
+  npm run validate:strict
+  ```
+- [ ] Test the CLI commands:
+  ```bash
+  node bin/aos-store.mjs list | head -n 20
+  node bin/aos-store.mjs search django
+  node bin/aos-store.mjs search spring
+  ```
+- [ ] Test mock installation:
+  ```bash
+  node bin/aos-store.mjs install <test-skill> --dry-run
+  ```
+- [ ] Ensure Git working tree is clean and commits follow Conventional Commits:
+  - `feat(store): add build-ecc-store-index generator and store-index.json`
+  - `feat(store): implement aos-store CLI and installer integration`
+  - `feat(dispatcher): suggest aos store install on missing mandatory skills`
+  - `docs(ask-tim): add ECC store fallback section`
+
+---
+
+## 🚀 4. Definition of Done
+1. `npm test` and `npm run validate` pass with zero errors.
+2. `lib/ecc-store-index.json` is generated, valid JSON, under 100 KB.
+3. `bin/aos-store.mjs` executes cleanly without unhandled rejections.
+4. Worktree is ready for review and merge into `main`.

package/docs/handover/agenttrail-for-ao.md

@@ -0,0 +1,58 @@
+# agenttrail for AO — waiting questions & GO/Nein handover
+
+AO (the Go daemon shipped as `@hybridlabor-api/bdb-agent-orchestrator`, binary at `~/.local/bin/ao`) can mirror what the agenttrail live map shows: an agent that waits on the human appears as a question with GO / Nein, and AO surfaces "Needs you" in its own UI — then types the human's decision into the waiting session (approved_plan_go.md:25, :57). agenttrail is the live-map daemon vendored into AOS at `skills/global_config/agenttrail/bin/agenttrail.mjs`, run as `aos-trail`; one daemon per repo, bound to 127.0.0.1 only. This document lists the HTTP surfaces AO may call and the things it must never do. The ask/answer endpoints are the AOS patch defined in production_artifacts/00_execution_plan.md ({#ask-engine}, lines 8-13) and production_artifacts/approved_plan_go.md; `/whoami` and `/model` already exist in the vendored daemon (agenttrail.mjs:583-584, :674-675).
+
+## What AO calls
+
+### 1. Find the repo's daemon — `GET /whoami`
+
+Probe `http://127.0.0.1:5330` through `5344` and match `repoPath` against the repo AO is working in — the same pattern the daemon itself uses for boot dedup (agenttrail.mjs:733-741):
+
+```sh
+curl -s http://127.0.0.1:$p/whoami
+# {"project":"aos","port":5330,"repoPath":"/Users/tim/dev/bdb-dev/aos-wt-go"}
+```
+
+Stop at the first match. If no daemon answers there is nothing to mirror — do not spawn a daemon from AO; the asker's CLI already prints `start: aos-trail . --plan …` on stderr (00_execution_plan.md:5). The `AGENTTRAIL_PORT` env var pins a single port and wins over the probe range (agenttrail.mjs:91).
+
+### 2. Read open questions — `GET /model`, `GET /ask/<id>`, `GET /events`
+
+- `GET /model` carries `asks`: one object per question `{id, question, askedBy, askedAt, expiryAt, status: 'pending' | 'go' | 'deny', decidedAt, by, expired}`. Show every ask, oldest first (`askedAt` ascending — approved_plan_go.md:36).
+- `GET /ask/<id>` returns one ask plus the last 10 decisions — the "wer · wann · was" log (00_execution_plan.md:13).
+- `GET /events` is the SSE stream; activity ticks carry `asks` too (00_execution_plan.md:10), so AO can mirror live instead of polling.
+
+A pending question past `expiryAt` flips to `status: 'deny'` with `expired: true` — render it greyed out (abgelaufen), never as a live GO/Nein pair (00_execution_plan.md:52).
+
+### 3. Answer — `POST /answer`
+
+```sh
+curl -s -X POST http://127.0.0.1:$port/answer \
+  -H 'Content-Type: application/json' \
+  --data '{"id":"<ask-id>","decision":"go"}'   # or "deny"
+```
+
+- The `content-type` header must be exactly `application/json` — a missing or different header (`text/plain`, JSON with a charset suffix) is rejected (00_execution_plan.md:13).
+- The body `{id, decision}` is capped at 4 KB.
+- `origin`: browser callers always send it, and it must equal the daemon's own `http://localhost:<port>` or `http://127.0.0.1:<port>`; AO is a local non-browser caller and may omit the header entirely (00_execution_plan.md:51 — the curl above does). If AO sends an `origin`, it must be the daemon's own.
+- A valid answer sets the ask's status + `decidedAt` + `by: 'you'` and appends `{question, decision, by, at}` to the timestamped decision log; timeout denials land there too, as `by: 'timeout'` (00_execution_plan.md:13).
+- The daemon binds 127.0.0.1 only (agenttrail.mjs:700) and sets no `Access-Control-*` header and no `OPTIONS` handler anywhere in its route chain (agenttrail.mjs:572-689) — that absence is the CSRF protection for the map's browser buttons. AO must not ask for CORS to be relaxed.
+
+That is the whole surface: AO does not call the daemon's other mutating endpoints (`/spawn`, `/setup`, `/setup-board`, `/hook`) and never writes into the repo — the daemon itself never touches the repo; state lives under `~/.agenttrail` (agenttrail.mjs:307).
+
+## What the answer means
+
+`aos-trail ask "<question>"` blocks until the question is answered or expires and exits 0 on go, 1 on deny/timeout (00_execution_plan.md:5). The default deadline is 30 minutes, overridable per question via the asker's `--timeout <10s|30m|2h|N>`; expiry auto-denies and is logged like a human decision (00_execution_plan.md:52). Questions and the decision log persist across daemon restarts in `~/.agenttrail/<repo-hash>.json` (agenttrail.mjs:308).
+
+## Mirroring in AO's UI
+
+- Pending ask → a pinned "Needs you" card with the question, the asking agent (`askedBy`), elapsed time, and one GO and one Nein button.
+- AO answers `POST /answer` only after the human clicked or said the decision for that exact ask id, and only then may it type that decision into the waiting session (approved_plan_go.md:57 — AO already recognizes "Needs You GO" and can write to the terminal, :25).
+- Re-check `GET /ask/<id>` immediately before typing: the human may have answered on the map instead, or the question may have expired meanwhile.
+
+## Hard rules
+
+- The AO button never authorizes `git push`, `npm publish`, `npm version` or recursive `rm` (approved_plan_go.md:30). Those four stay under go-gate's sole authority (`.claude/hooks/go-gate.mjs:43-49`), which opens only for the literal, human-typed `GO` as the last message in the session transcript (go-gate.mjs:10-13, transcript-only check in main() :116-151). The ask/answer flow only resolves explicit `aos-trail ask` questions and never writes to any session transcript — the map and AO remain "an observer and an answer relay, never a permission system" (00_execution_plan.md:50, approved_plan_go.md:49).
+- Never answer without the human. No batching, no defaults, no "the agent seemed sure" — one answer per explicit human decision, per question id.
+- Never auto-retry a timed-out question. Expiry → deny is final (`by: 'timeout'` in the log); only the human asking again starts a new question (approved_plan_go.md:57; the same "no silent retries / a fresh GO per action" rule the gate runs on, go-gate.mjs:13).
+- Never read `~/.agenttrail/<repo-hash>.json` or anything else inside `~/.agenttrail/` directly (agenttrail.mjs:307-308). Those files are internal state with no format contract — use the HTTP surfaces above.
+- Keep the CSRF contract intact: exact `Content-Type: application/json`, own-or-absent `origin`, and never relay an answer through web content the agent loaded.

package/docs/handover/deja-for-ao.md

@@ -0,0 +1,51 @@
+# deja for AO — session-memory handover
+
+AO (the Go daemon shipped as `@hybridlabor-api/bdb-agent-orchestrator`, binary at `~/.local/bin/ao`) can ask deja — the local session-memory engine installed together with memB by the AOS installer — for project history. This document lists the surfaces AO may call and the two things it must not do. Every command below is verified against deja-vu 0.21.1.
+
+## What AO calls at session start
+
+Run in the project directory:
+
+```sh
+deja wip --json
+```
+
+The answer is what the last session in that directory was doing (deja-vu docs/json-output.md:1192-1223):
+
+```json
+{
+  "schema_version": 2,
+  "session": "ses_fb76fff…",
+  "harness": "opencode",
+  "asked": "the orders worker is exhausting its database connections under load",
+  "decision": "bound every orders-worker query with a context",
+  "files": ["internal/worker/orders.go"],
+  "command": "go test ./internal/worker/...",
+  "command_failed": true,
+  "lines": ["working on: …", "settled: …"]
+}
+```
+
+- `schema_version: 2` is the only guaranteed field. Every other field is optional and omitted when the transcript does not carry it — treat all of them as nullable.
+- `lines` is the inject-verbatim form: one string per fact, in display order. A caller that wants to show the digest reads `lines` and does not re-assemble the fields.
+
+## Untrusted historical data
+
+Everything deja returns is transcript-derived and may carry text an attacker influenced: a directive copied from a web page persists in the index and replays into later sessions. deja-vu wraps its own agent-facing recall in `<deja-recall>` markers with an untrusted-data preamble (deja-vu docs/SECURITY-MODEL.md:235-245). AO must label or wrap the content the same way before it reaches a model, and instructions inside it must not be followed.
+
+## Other surfaces AO may use
+
+- `deja fix "<error>" --json` — what this machine ran after that error. Rows carry `command` or `edit`; `candidate: true` marks ran-next-but-unconfirmed evidence, not a guaranteed fix (deja-vu docs/json-output.md:763).
+- `deja last --json` — recent session metadata, never message bodies (deja-vu docs/json-output.md:200).
+- `deja handoff [id-prefix]` — the handoff digest for a session (deja-vu CLI reference, docs/guide/commands.html).
+- `deja blame <path> --json` — which sessions discussed a file; a top-level JSON array, no envelope (deja-vu docs/json-output.md:1107).
+- `deja doctor --json --offline` — index and store health; `--offline` keeps the version check off the network (deja-vu docs/json-output.md:356).
+
+## Stability contract
+
+Envelope-shaped answers carry `schema_version: 2`. Within a version, changes are additive only: existing field names, types and meanings stay the same. Bumping the version signals a breaking change, so branch on `schema_version` before parsing the rest of the envelope (deja-vu docs/json-output.md:7-28). `deja blame --json` returns a bare array and carries no version; its element shapes are stable.
+
+## Hard rules
+
+- Never read `~/.cache/deja/index.db` or anything else inside the index directory (`manifest.gob`, `sessions.gob`, `records.bin`, the buckets, the sidecars) directly. The format has moved forty-odd times and is explicitly not a contract (deja-vu docs/INTEGRATING.md:102-106). Use the CLI surfaces above.
+- AO must NOT run `deja install --auto` and must not wire session-start auto-recall. The approved AOS plan rules both out (production_artifacts/approved_plan_deja.md:61-66): a second writer into agent configs, and old history injected automatically at every session start, are exactly the injection vectors AOS installed deja to avoid. AO calls the `deja` CLI itself, on demand, in the project directory.