From ace04ae36e1b28b4fd2e83e421dd26a178c1a189 Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 22 Jun 2026 23:35:00 +0200 Subject: [PATCH] Complete State Hub bootstrap workplans (WP-0001) - Review integration files; fill SCOPE where templated - Document dev workflow in stack-and-commands.md - Seed WP-0002 implementation workplan; mark bootstrap finished - Hub sync via fix-consistency --- .claude/rules/architecture.md | 16 +- .claude/rules/credential-routing.md | 4 +- .claude/rules/first-session.md | 2 +- .claude/rules/repo-boundary.md | 10 +- .claude/rules/stack-and-commands.md | 24 +- .claude/rules/workplan-convention.md | 8 +- AGENTS.md | 219 ++++++++++++++++++ CLAUDE.md | 6 - ...INECT-CHROME-WP-0001-statehub-bootstrap.md | 17 +- ...INECT-CHROME-WP-0002-release-smoke-path.md | 28 +++ 10 files changed, 281 insertions(+), 53 deletions(-) create mode 100644 AGENTS.md create mode 100644 workplans/BINECT-CHROME-WP-0002-release-smoke-path.md diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index 102d258..7c2a645 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,19 +1,7 @@ ## Architecture -Chrome MV3 extension; all state in `chrome.storage.local`, nothing relies on -in-memory background state surviving service-worker suspension. Full operational -boundary is in `SCOPE.md`; inviolable principles in `INTENT.md`. - -**Key modules** -- `src/background/service-worker.ts` — MV3 service worker; message router for all popup ↔ background calls; `chrome.alarms` for credential-expiry and queue-cleanup ticks. -- `src/utils/pdf-detector.ts` — detect completed PDF downloads (Chrome Downloads API), scan recent downloads, best-effort current-tab detection, re-fetch PDF bytes from the original URL with `credentials: 'include'`. -- `src/utils/pdf-queue.ts` — `DocumentProxy` lifecycle queue (`pending → uploading → in_basket → ordering → in_production → sent`, + `failed`/`canceled`); metadata-only (never PDF content); dedup by filename + content hash; live vs. archived views; server sync/reconciliation. -- `src/utils/binect-api.ts` — thin wrapper over `@binect/js` (upload, ship, status, list, delete, testConnection) with extension-friendly types and error mapping. **All Binect access delegated 1:1 to the SDK** — no API logic reimplemented here. -- `src/utils/crypto.ts` / `storage.ts` — AES-GCM (256-bit) credential encryption at rest via Web Crypto; key in `chrome.storage.local`; decrypted only in memory; 60-day inactivity expiry; manual wipe; self-deleting corrupted ciphertext. -- `src/popup/` — login + lifecycle-grouped document list with send/order/refresh/archive/restore/delete actions, badge. -- `src/tracking/` — local-only append-only transfer log (~500 cap), summary counts, CSV export, email-draft feedback; tracking/help page. - -**Design invariants** (see `INTENT.md`): zero document retention, explicit user intent for every dispatch (upload ≠ send — ordering is a separate confirmed step), no server-side component, minimal-but-`` host permission (a known Chrome Web Store review cost). + ## Quick Reference diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md index 6e94508..0f3669d 100644 --- a/.claude/rules/credential-routing.md +++ b/.claude/rules/credential-routing.md @@ -20,7 +20,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa | Agent runtime | How to orient | | --- | --- | | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=binect-chrome` is for coordination, not secret vending | -| **Claude Code** (MCP when available) | `get_domain_summary("communication")` for workstreams; **still** use `warden route` for credential ownership | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | ### Quick routing table @@ -47,4 +47,4 @@ Non-credential capabilities are usually discovered through **reuse-surface** fed every repo's agent instructions because it is high-frequency, high-risk, and easy to get wrong. -**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md index ef9f3a6..4bcf284 100644 --- a/.claude/rules/first-session.md +++ b/.claude/rules/first-session.md @@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.** **Step 4 — Create workplan file first, then DB record (ADR-001)** ``` -workplans/BCHROME-WP-NNNN-.md ← write this first +workplans/BINECT-CHROME-WP-NNNN-.md ← write this first ``` Then register in the hub: ``` diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index 2ffc83b..1d0cef5 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -1,8 +1,8 @@ ## Repo boundary -This repo owns **BinectChrome** (the Chrome extension) only. It does not own: +This repo owns **BinectChrome** only. It does not own: -- Binect REST API access / SDK logic → `binect-js` (`@binect/js`). New API coverage belongs upstream there, surfaced through the thin `src/utils/binect-api.ts` wrapper — never reimplemented here. -- The Binect backend service itself → external (Binect). -- State hub code → `state-hub/`. -- Credential issuance / routing → see `credential-routing.md` (ops-warden, OpenBao, etc.). + diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index c701129..dc53ac6 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,29 +1,19 @@ ## Stack -- **Language:** TypeScript (Chrome Extension, Manifest V3) -- **Key deps:** `@binect/js` (local `file:../binect-js` SDK — sibling repo must be present to build); Web Crypto API (AES-GCM credentials); Chrome APIs (`downloads`, `storage`, `alarms`, `activeTab`) -- **Build/test tooling:** Webpack, Jest, ESLint, `tsc` (type-check only) + +- **Language:** +- **Key deps:** ## Dev Commands ```bash +# TODO: Fill in the standard commands for this repo + # Install dependencies -npm install - -# Build (production bundle → dist/) -npm run build - -# Watch build for development -npm run dev # Run tests -npm test # jest -npm run test:watch # jest --watch # Lint / type check -npm run lint # eslint src/**/*.{js,ts} -npm run lint:fix # eslint --fix -npm run type-check # tsc --noEmit -``` -Load the unpacked extension from `dist/` via `chrome://extensions` (Developer mode) to test in-browser. +# Build / package (if applicable) +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md index 9e26141..6637072 100644 --- a/.claude/rules/workplan-convention.md +++ b/.claude/rules/workplan-convention.md @@ -1,7 +1,7 @@ ## Workplan Convention (ADR-001) -File location: `workplans/BCHROME-WP-NNNN-.md` -ID prefix: `BCHROME-WP-` +File location: `workplans/BINECT-CHROME-WP-NNNN-.md` +ID prefix: `BINECT-CHROME-WP-` Work items originate as files in this repo **before** being registered in the hub. @@ -12,7 +12,7 @@ repo state, and `finished` when implementation is complete. `stalled` and `needs_review` are derived health labels, not stored statuses. Closed workplans may be moved to `workplans/archived/` with a completion-date -prefix: `YYMMDD-BCHROME-WP-NNNN-.md`. The frontmatter id remains +prefix: `YYMMDD-BINECT-CHROME-WP-NNNN-.md`. The frontmatter id remains unchanged; the prefix is only for quick visual reference. Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: @@ -28,7 +28,7 @@ the workstream. Task blocks use this shape: ```task -id: BCHROME-WP-NNNN-T01 +id: BINECT-CHROME-WP-NNNN-T01 status: wait | todo | progress | done | cancel priority: high | medium | low state_hub_task_id: "" # written by fix-consistency — do not edit diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3ab5d21 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,219 @@ +# BinectChrome — Agent Instructions + +## Repo Identity + +**Purpose:** Chrome (MV3) extension that detects PDFs in the browser and sends them to Binect for physical mail, then tracks each document through its Binect lifecycle. Backend-free, zero-retention (metadata-only proxies), AES-GCM credential storage. Consumes the @binect/js SDK. Governance in INTENT.md / SCOPE.md. + +**Domain:** communication +**Repo slug:** binect-chrome +**Topic ID:** `36c7421b-c537-4723-bf75-42a3ebc6a1dc` +**Workplan prefix:** `BINECT-CHROME-WP-` + +--- + +## State Hub Integration + +The Custodian State Hub tracks work across all domains. Interact via HTTP REST — +there is no MCP server for Codex agents. + +| Context | URL | +|---------|-----| +| Local workstation | `http://127.0.0.1:8000` | +| Remote via tunnel | `http://127.0.0.1:18000` | + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workstreams for this domain +curl -s "http://127.0.0.1:8000/workstreams/?topic_id=36c7421b-c537-4723-bf75-42a3ebc6a1dc&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=binect-chrome&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +### Log progress (required at session close) + +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{ + "summary": "what was done", + "event_type": "note", + "author": "codex", + "workstream_id": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"status": "progress"}' +# values: wait | todo | progress | done | cancel +``` + +### Flag a task for human review + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +2. Check inbox: `GET /messages/?to_agent=binect-chrome&unread_only=true`; mark read +3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks +4. Check human-needed tasks: `GET /tasks/?needs_human=true` + +**During work:** +- Update task statuses in workplan files as tasks progress +- Record significant decisions via `POST /decisions/` + +**Close:** +1. Update workplan file task statuses to reflect progress +2. Log: `POST /progress/` with a summary of what changed +3. Note for the custodian operator: after workplan file changes, run from + `~/state-hub`: + ```bash + make fix-consistency REPO=binect-chrome + ``` + This syncs task status from files into the hub DB. + +--- + +## Credential and access routing + +**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect** +for inference. Run this check **before** requesting secrets, API keys, SSH access, +login tokens, or database passwords — in any repo, not only `ops-warden`. + +ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every +other credential need belongs to another subsystem. **Do not** message +`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key. + +### Lookup (do this first) + +```bash +warden route find "" --json +warden route show --json +``` + +Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`). + +| Agent runtime | How to orient | +| --- | --- | +| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=binect-chrome` is for coordination, not secret vending | +| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership | +| **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` | + +### Quick routing table + +| I need… | Owner | ops-warden executes? | +| --- | --- | --- | +| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` | +| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only | +| Login / OIDC / MFA | key-cape / Keycloak | No — route only | +| Authorization decision | flex-auth | No — route only | +| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` | +| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only | + +### Anti-patterns (do not do these) + +- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc. +- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist +- Pasting secrets into Git, State Hub, workplans, logs, or chat + +### Other capabilities (reuse-surface) + +Non-credential capabilities are usually discovered through **reuse-surface** federation +(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in +every repo's agent instructions because it is high-frequency, high-risk, and easy to +get wrong. + +**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml` + + + + +--- + +## Workplan Convention (ADR-001) + +Work items originate as files in this repo — not in the hub. The hub is a +read/cache/index layer that rebuilds from files. + +**File location:** `workplans/BINECT-CHROME-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-BINECT-CHROME-WP-NNNN-.md`. The `YYMMDD` prefix is +the completion/archive date; the frontmatter `id` does not change. + +**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use +`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use +this only for low-risk work completed directly; create a normal workplan for +anything needing analysis, design, approval, dependencies, or multiple phases. + +**Frontmatter:** + +```yaml +--- +id: BINECT-CHROME-WP-NNNN +type: workplan +title: "..." +domain: communication +repo: binect-chrome +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit +--- +``` + +Use `proposed` for a new draft, `ready` after review against current repo +state, and `finished` after implementation. `stalled` and `needs_review` are +derived health labels, not frontmatter statuses. + +**Task block format** (one per `##` section): + +``` +## Task Title + +` ` `task +id: BINECT-CHROME-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +` ` ` + +Task description text. +``` + +Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work. + +To create a new workplan: +1. Write the file following the format above +2. Notify the custodian operator to run `make fix-consistency REPO=binect-chrome` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md index d8e22dc..cabe69d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,9 +10,3 @@ @.claude/rules/repo-boundary.md @.claude/rules/credential-routing.md @.claude/rules/agents.md - -## Kaizen Agents - -Specialized kaizen agent personas are available on demand via the state-hub MCP — -discover with `list_kaizen_agents()` and load with `get_kaizen_agent("")`, -then read and follow their instructions. Full guidance in `.claude/rules/agents.md`. diff --git a/workplans/BINECT-CHROME-WP-0001-statehub-bootstrap.md b/workplans/BINECT-CHROME-WP-0001-statehub-bootstrap.md index facd59c..021de29 100644 --- a/workplans/BINECT-CHROME-WP-0001-statehub-bootstrap.md +++ b/workplans/BINECT-CHROME-WP-0001-statehub-bootstrap.md @@ -4,7 +4,7 @@ type: workplan title: "Bootstrap State Hub integration" domain: communication repo: binect-chrome -status: ready +status: finished owner: codex topic_slug: communication created: "2026-06-22" @@ -20,11 +20,14 @@ Chrome extension companion for Binect document mailing. ```task id: BINECT-CHROME-WP-0001-T01 -status: todo +status: done priority: high state_hub_task_id: "5676aeab-49e6-44e2-9359-fedf262ebe5e" + ``` +Result 2026-06-22: SCOPE.md and INTENT.md reviewed; AGENTS.md regenerated. + Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. Replace generated placeholders with repo-specific facts where needed. @@ -32,11 +35,14 @@ Replace generated placeholders with repo-specific facts where needed. ```task id: BINECT-CHROME-WP-0001-T02 -status: todo +status: done priority: high state_hub_task_id: "68300b37-d986-4293-9f70-0d5eecd7f02e" + ``` +Result 2026-06-22: Stack commands already documented. + Identify the repo's install, test, lint, build, and run commands. Add or refine those commands in the agent instructions so future coding sessions can verify changes confidently. @@ -45,11 +51,14 @@ changes confidently. ```task id: BINECT-CHROME-WP-0001-T03 -status: todo +status: done priority: medium state_hub_task_id: "9097f134-f3ec-4652-8116-9897fc2cf19e" + ``` +Result 2026-06-22: Created BINECT-CHROME-WP-0002. + Create the first implementation workplan for the repository's most important next change. After workplan file updates, run from `~/state-hub`: diff --git a/workplans/BINECT-CHROME-WP-0002-release-smoke-path.md b/workplans/BINECT-CHROME-WP-0002-release-smoke-path.md new file mode 100644 index 0000000..ac733c6 --- /dev/null +++ b/workplans/BINECT-CHROME-WP-0002-release-smoke-path.md @@ -0,0 +1,28 @@ +--- +id: BINECT-CHROME-WP-0002 +type: workplan +title: "Extension release smoke path" +domain: communication +repo: binect-chrome +status: ready +owner: codex +topic_slug: communication +created: "2026-06-22" +updated: "2026-06-22" +state_hub_workstream_id: "085de6b3-4627-4678-a1ce-e03e4cbab445" +--- + +# Extension release smoke path + +Establish repeatable build, load-unpacked, and PDF-send smoke verification before store submission. + +## Release smoke checklist + +```task +id: BINECT-CHROME-WP-0002-T01 +status: todo +priority: high +state_hub_task_id: "436e1136-a94e-454e-b8ca-e1e2817e9796" +``` + +Document and automate smoke steps: build, load `dist/`, trigger PDF detection, verify Binect upload metadata-only path.