generated from coulomb/repo-seed
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
This commit is contained in:
@@ -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-`<all_urls>` host permission (a known Chrome Web Store review cost).
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
|
||||
## Quick Reference
|
||||
|
||||
|
||||
@@ -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`
|
||||
@@ -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-<slug>.md ← write this first
|
||||
workplans/BINECT-CHROME-WP-NNNN-<slug>.md ← write this first
|
||||
```
|
||||
Then register in the hub:
|
||||
```
|
||||
|
||||
@@ -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.).
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
|
||||
@@ -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)
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **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)
|
||||
```
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
## Workplan Convention (ADR-001)
|
||||
|
||||
File location: `workplans/BCHROME-WP-NNNN-<slug>.md`
|
||||
ID prefix: `BCHROME-WP-`
|
||||
File location: `workplans/BINECT-CHROME-WP-NNNN-<slug>.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-<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.
|
||||
|
||||
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: "<uuid>" # written by fix-consistency — do not edit
|
||||
|
||||
219
AGENTS.md
Normal file
219
AGENTS.md
Normal 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/`)
|
||||
@@ -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("<name>")`,
|
||||
then read and follow their instructions. Full guidance in `.claude/rules/agents.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`:
|
||||
|
||||
|
||||
28
workplans/BINECT-CHROME-WP-0002-release-smoke-path.md
Normal file
28
workplans/BINECT-CHROME-WP-0002-release-smoke-path.md
Normal 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.
|
||||
Reference in New Issue
Block a user