coulomb/binect-chrome
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

Complete State Hub bootstrap workplans (WP-0001)

Browse Source 
- 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
This commit is contained in:
Bernd Worsch
2026-06-22 23:35:00 +02:00
parent cbc4e5160a
commit ace04ae36e
10 changed files with 281 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
.claude/rules/architecture.md
View File

@@ -1,19 +1,7 @@
## Architecture ## Architecture
Chrome MV3 extension; all state in `chrome.storage.local`, nothing relies on <!-- TODO: Describe the key design decisions and component structure.
in-memory background state surviving service-worker suspension. Full operational Key modules, data flows, external integrations, state machines, etc. -->
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-`<all_urls>` host permission (a known Chrome Web Store review cost).
## Quick Reference ## Quick Reference

4
.claude/rules/credential-routing.md
View File

@@ -20,7 +20,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
| Agent runtime | How to orient | | 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 | | **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` | | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
### Quick routing table ### 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 every repo's agent instructions because it is high-frequency, high-risk, and easy to
get wrong. 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`

2
.claude/rules/first-session.md
View File

@@ -17,7 +17,7 @@ roadmap phase. **Wait for approval before creating.**
**Step 4 — Create workplan file first, then DB record (ADR-001)** **Step 4 — Create workplan file first, then DB record (ADR-001)**
``` ```
workplans/BCHROME-WP-NNNN-<slug>.md ← write this first workplans/BINECT-CHROME-WP-NNNN-<slug>.md ← write this first
``` ```
Then register in the hub: Then register in the hub:
``` ```

10
.claude/rules/repo-boundary.md
View File

@@ -1,8 +1,8 @@
## Repo boundary ## 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. <!-- TODO: List what belongs in adjacent repos, e.g.:
- The Binect backend service itself → external (Binect). - SSH key management → railiance-infra/
- State hub code → `state-hub/`. - State hub code → state-hub/
- Credential issuance / routing → see `credential-routing.md` (ops-warden, OpenBao, etc.). -->

24
.claude/rules/stack-and-commands.md
View File

@@ -1,29 +1,19 @@
## Stack ## Stack
- **Language:** TypeScript (Chrome Extension, Manifest V3) <!-- TODO: Fill in language, frameworks, and key dependencies -->
- **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`) - **Language:**
- **Build/test tooling:** Webpack, Jest, ESLint, `tsc` (type-check only) - **Key deps:**
## Dev Commands ## Dev Commands
```bash ```bash
# TODO: Fill in the standard commands for this repo
# Install dependencies # Install dependencies
npm install
# Build (production bundle → dist/)
npm run build
# Watch build for development
npm run dev
# Run tests # Run tests
npm test # jest
npm run test:watch # jest --watch
# Lint / type check # 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)
```

8
.claude/rules/workplan-convention.md
View File

@@ -1,7 +1,7 @@
## Workplan Convention (ADR-001) ## Workplan Convention (ADR-001)
File location: `workplans/BCHROME-WP-NNNN-<slug>.md` File location: `workplans/BINECT-CHROME-WP-NNNN-<slug>.md`
ID prefix: `BCHROME-WP-` ID prefix: `BINECT-CHROME-WP-`
Work items originate as files in this repo **before** being registered in the hub. 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. `needs_review` are derived health labels, not stored statuses.
Closed workplans may be moved to `workplans/archived/` with a completion-date Closed workplans may be moved to `workplans/archived/` with a completion-date
prefix: `YYMMDD-BCHROME-WP-NNNN-<slug>.md`. The frontmatter id remains prefix: `YYMMDD-BINECT-CHROME-WP-NNNN-<slug>.md`. The frontmatter id remains
unchanged; the prefix is only for quick visual reference. unchanged; the prefix is only for quick visual reference.
Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**: Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
@@ -28,7 +28,7 @@ the workstream.
Task blocks use this shape: Task blocks use this shape:
```task ```task
id: BCHROME-WP-NNNN-T01 id: BINECT-CHROME-WP-NNNN-T01
status: wait | todo | progress | done | cancel status: wait | todo | progress | done | cancel
priority: high | medium | low priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit

219
AGENTS.md Normal file
View File

@@ -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/<id>/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": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-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/<task_id>" \
-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 "<describe your need>" --json
warden route show <catalog-id> --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`
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## 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-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-BINECT-CHROME-WP-NNNN-<slug>.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: "<uuid>" # 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: "<uuid>" # 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/`)

6
CLAUDE.md
View File

@@ -10,9 +10,3 @@
@.claude/rules/repo-boundary.md @.claude/rules/repo-boundary.md
@.claude/rules/credential-routing.md @.claude/rules/credential-routing.md
@.claude/rules/agents.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("<name>")`,
then read and follow their instructions. Full guidance in `.claude/rules/agents.md`.

17
workplans/BINECT-CHROME-WP-0001-statehub-bootstrap.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Bootstrap State Hub integration" title: "Bootstrap State Hub integration"
domain: communication domain: communication
repo: binect-chrome repo: binect-chrome
status: ready status: finished
owner: codex owner: codex
topic_slug: communication topic_slug: communication
created: "2026-06-22" created: "2026-06-22"
@@ -20,11 +20,14 @@ Chrome extension companion for Binect document mailing.
```task ```task
id: BINECT-CHROME-WP-0001-T01 id: BINECT-CHROME-WP-0001-T01
status: todo status: done
priority: high priority: high
state_hub_task_id: "5676aeab-49e6-44e2-9359-fedf262ebe5e" 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`. Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
Replace generated placeholders with repo-specific facts where needed. Replace generated placeholders with repo-specific facts where needed.
@@ -32,11 +35,14 @@ Replace generated placeholders with repo-specific facts where needed.
```task ```task
id: BINECT-CHROME-WP-0001-T02 id: BINECT-CHROME-WP-0001-T02
status: todo status: done
priority: high priority: high
state_hub_task_id: "68300b37-d986-4293-9f70-0d5eecd7f02e" 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 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 those commands in the agent instructions so future coding sessions can verify
changes confidently. changes confidently.
@@ -45,11 +51,14 @@ changes confidently.
```task ```task
id: BINECT-CHROME-WP-0001-T03 id: BINECT-CHROME-WP-0001-T03
status: todo status: done
priority: medium priority: medium
state_hub_task_id: "9097f134-f3ec-4652-8116-9897fc2cf19e" 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 Create the first implementation workplan for the repository's most important
next change. After workplan file updates, run from `~/state-hub`: next change. After workplan file updates, run from `~/state-hub`:

28
workplans/BINECT-CHROME-WP-0002-release-smoke-path.md Normal file
View File

@@ -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.