diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md index 7c2a645..8ce72e9 100644 --- a/.claude/rules/architecture.md +++ b/.claude/rules/architecture.md @@ -1,7 +1,37 @@ ## Architecture - +The repo has two layers: + +1. Root framework layer +- `INTENT.md`, `docs/`, `research/`, and `registry/` define the generic + adaptive-pricing vocabulary, lifecycle model, and roadmap. +- `workplans/` is the repo-native source of truth for tracked work (ADR-001). + +2. Project implementation layer +- `projects/coulomb-pricing/` contains the first concrete deployment: + Coulomb Social's Economic Observatory MVP. +- `observatory/` is a small Python package that reads JSON ledgers and + registries from `data/`, computes economics snapshots, and serves a local UI. + +Current Coulomb data flow: +- `data/*.json` ledgers and registries +- `observatory/load.py` parses JSON into dataclasses +- `observatory/ledger.py` builds monthly cost rows +- `observatory/economics.py` computes liquidity, margins, and snapshots +- `observatory/allocation.py`, `usage.py`, `pricing_context.py`, + `simulator.py`, `credits.py`, and `recommendations.py` derive higher-level + pricing views +- `observatory/api.py` assembles the dashboard payload +- `observatory/__main__.py` renders the Markdown report +- `observatory/server.py` exposes `/api/dashboard` and serves `ui/` + +External integrations are file-based in MVP: +- Bubble export importer +- Stripe export importer +- OpenRouter export importer + +The internal model and ledgers are the source of truth. Provider exports feed +the ledgers; they do not replace them. ## Quick Reference diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md index 4f2e3c1..a117200 100644 --- a/.claude/rules/repo-boundary.md +++ b/.claude/rules/repo-boundary.md @@ -1,8 +1,12 @@ ## Repo boundary This repo owns **adaptive-pricing** only. It does not own: - - +- State Hub server code, DB schema, or consistency tooling → `~/state-hub` +- SSH certificates, login flows, or secret vending → `ops-warden`, + `ops-bridge`, OpenBao, Keycloak, and related custody systems +- Bubble.io, Stripe, or OpenRouter product runtimes themselves; this repo only + models or imports their pricing-relevant data +- Generic whynot-design source assets; this repo only vendors the UI artifacts + needed by `projects/coulomb-pricing/ui/` +- Unrelated Coulomb or marketplace application code outside + `projects/coulomb-pricing/` diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md index 34f4f63..09483dc 100644 --- a/.claude/rules/repo-identity.md +++ b/.claude/rules/repo-identity.md @@ -2,4 +2,9 @@ **Domain:** financials **Repo slug:** adaptive-pricing +**State Hub topic:** helix-forge **Topic ID:** f39fa2a3-c491-414c-a91b-b4c5fcc6139c + +Repo classification and hub topic are intentionally separate here: +- Repo/business domain: `financials` +- Shared hub topic: `helix-forge` in the hub's `infotech` domain diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md index 19ece28..182d158 100644 --- a/.claude/rules/session-protocol.md +++ b/.claude/rules/session-protocol.md @@ -13,6 +13,8 @@ Then call the MCP tool for richer cross-domain context when MCP tools are expose ``` get_domain_summary("financials") ``` +Repo-specific work tracking still syncs through topic +`f39fa2a3-c491-414c-a91b-b4c5fcc6139c` (`helix-forge`). If MCP tools are unavailable in the current agent session, use the REST API: ```bash curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool @@ -44,7 +46,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending **Step 4 — Present brief** -1. **Active workstreams** for `financials` — title, task counts, blocking decisions +1. **Repo-relevant workstreams** under topic `helix-forge` — title, task counts, blocking decisions 2. **Pending tasks** from `workplans/` + any `[repo:adaptive-pricing]` hub tasks 3. **Goal guidance** — if `goal_guidance` in summary: - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* @@ -73,12 +75,16 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \ If workplan files were modified, ensure the local copy is up to date first: ```bash git -C pull --ff-only -cd ~/state-hub && make fix-consistency REPO=adaptive-pricing +statehub fix-consistency ``` -For repos where implementation runs on a remote machine (e.g. CoulombCore), -use the combined target which pulls before fixing: +Fallback when the CLI is unavailable: ```bash -cd ~/state-hub && make fix-consistency-remote REPO=adaptive-pricing +/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ + fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing +``` +Legacy wrapper: +```bash +cd ~/state-hub && make fix-consistency REPO=adaptive-pricing ``` **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback will sync the file to match DB. **C-16** (repo behind remote) blocks all writes diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md index dc53ac6..658c151 100644 --- a/.claude/rules/stack-and-commands.md +++ b/.claude/rules/stack-and-commands.md @@ -1,19 +1,28 @@ ## Stack - -- **Language:** -- **Key deps:** +- **Language:** Markdown-heavy repo with a Python 3 implementation subtree +- **Key deps:** Python stdlib for the observatory runtime, `pytest` for tests, + optional `make` for wrappers, whynot-design vendored UI assets in + `projects/coulomb-pricing/ui/vendor/` ## Dev Commands ```bash -# TODO: Fill in the standard commands for this repo +# Root repo: metadata/workplan sync +statehub fix-consistency +/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ + fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing -# Install dependencies +# Project runtime +cd /home/worsch/adaptive-pricing/projects/coulomb-pricing +python3 -m observatory --period 2026-06 +python3 -m observatory --period 2026-06 --output reports/economics-2026-06.md +python3 -m observatory.server -# Run tests +# Tests +python3 -m pytest -q +make test -# Lint / type check - -# Build / package (if applicable) +# UI vendor refresh +make design ``` diff --git a/.custodian-brief.md b/.custodian-brief.md index 0c1006b..46227a0 100644 --- a/.custodian-brief.md +++ b/.custodian-brief.md @@ -1,8 +1,8 @@ # Custodian Brief — adaptive-pricing -**Domain:** infotech -**Last synced:** 2026-06-22 21:23 UTC +**Domain:** financials +**Last synced:** 2026-07-02 08:19 UTC **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* ## Active Workstreams @@ -13,6 +13,6 @@ ## MCP Orientation (when available) If the state-hub MCP server is reachable, call: -`get_domain_summary("infotech")` +`get_domain_summary("financials")` This provides richer cross-domain context. If the MCP call fails, use this file as your orientation source. diff --git a/AGENTS.md b/AGENTS.md index 6e1266c..0527490 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,11 +4,17 @@ **Purpose:** Auto-regulating market value exploring price engine. -**Domain:** financials +**Primary repo domain:** financials **Repo slug:** adaptive-pricing +**State Hub topic:** `helix-forge` **Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` **Workplan prefix:** `ADAPTIVE-WP-` +`adaptive-pricing` is classified as a `financials` repo in +`.repo-classification.yaml`, but State Hub coordination currently runs through +the shared `helix-forge` topic in the hub's `infotech` domain. Keep repo-domain +fields (`domain`) and hub-topic fields (`topic_slug`, `topic_id`) distinct. + --- ## State Hub Integration @@ -27,7 +33,7 @@ there is no MCP server for Codex agents. # Offline brief — works without hub connection cat .custodian-brief.md -# Active workstreams for this domain +# Active workstreams for this repo's hub topic curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \ | python3 -m json.tool @@ -80,7 +86,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ ## Session Protocol **Start:** -1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe) +1. `cat .custodian-brief.md` — hub-topic goal and open workstreams (offline-safe) 2. Check inbox: `GET /messages/?to_agent=adaptive-pricing&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` @@ -92,12 +98,22 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ **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`: +3. After workplan file changes, run: ```bash + statehub fix-consistency + ``` + Fallback when the CLI is unavailable: + ```bash + /home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ + fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing + ``` + Legacy wrapper: + ```bash + cd ~/state-hub make fix-consistency REPO=adaptive-pricing ``` - This syncs task status from files into the hub DB. + Coding agents should run the direct CLI when available. This syncs task + status from files into the hub DB. --- @@ -161,7 +177,7 @@ get wrong. | Path | Purpose | |------|---------| | `INTENT.md`, `docs/`, `research/`, `registry/` | Generic adaptive-pricing framework | -| `projects//` | Deployment-specific MVP material (integrations, configs, project docs) | +| `projects//` | Deployment-specific implementations, integrations, data, and project docs | | `workplans/` | ADR-001 workplans and task tracking (including MVP execution plans) | Do not place project-specific MVP documentation in `specs/` or other generic @@ -169,6 +185,35 @@ paths. The Coulomb Social MVP lives under `projects/coulomb-pricing/`; its Coulomb MVP workplan is archived at `workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md`. +## Developer Workflow + +The root repo is documentation- and workplan-heavy. The current executable +runtime lives under `projects/coulomb-pricing/`. + +```bash +# Generate the Coulomb observatory Markdown report +cd projects/coulomb-pricing +python3 -m observatory --period 2026-06 + +# Start the local observatory UI +python3 -m observatory.server + +# Run tests when pytest is available +python3 -m pytest -q + +# Makefile wrappers when make is available +make test +make serve +make design + +# Sync workplan metadata back into the hub after workplan edits +statehub fix-consistency + +# Fallback when the CLI is not installed +/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \ + fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing +``` + --- ## Workplan Convention (ADR-001) @@ -194,11 +239,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases. id: ADAPTIVE-WP-NNNN type: workplan title: "..." -domain: helix_forge +domain: financials repo: adaptive-pricing status: proposed | ready | active | blocked | backlog | finished | archived owner: codex -topic_slug: ... +topic_slug: helix-forge created: "YYYY-MM-DD" updated: "YYYY-MM-DD" state_hub_workstream_id: "" # written by fix-consistency — do not edit @@ -228,5 +273,6 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo To create a new workplan: 1. Write the file following the format above -2. Notify the custodian operator to run `make fix-consistency REPO=adaptive-pricing` - (or send a message to the hub agent via `POST /messages/`) +2. Run `statehub fix-consistency` locally; use the direct CLI fallback above if + `statehub` is not installed. Ask the operator only if the CLI or State Hub + API is unavailable. diff --git a/README.md b/README.md index 0acca4d..e93dd84 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ pricing to payment-provider execution. ## Status -Early framework phase (documentation and research). First implementation: -[Economic Observatory MVP](workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md) (finished) -for Coulomb Social. \ No newline at end of file +Framework-first repo with one finished project-specific implementation: +[Economic Observatory MVP](workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md) +for Coulomb Social. The root remains the generic pricing framework; the current +runtime lives under `projects/coulomb-pricing/observatory/`. diff --git a/SCOPE.md b/SCOPE.md index d04fdf7..ef1cae5 100644 --- a/SCOPE.md +++ b/SCOPE.md @@ -25,9 +25,11 @@ adapting, and implementing pricing models across the product lifecycle. See ## Current State -- **Phase:** early framework — documentation, research, and registry scaffolding. -- **Runtime:** none in this repo yet; first implementation is the Coulomb Social - Economic Observatory MVP (`ADAPTIVE-WP-0002`). +- **Phase:** framework plus first project deployment — root docs/research remain + generic, while Coulomb Social provides the first concrete implementation. +- **Runtime:** project-specific runtime exists under + `projects/coulomb-pricing/observatory/`; the repo root remains documentation, + research, registry scaffolding, and workplan coordination. - **Bootstrap:** State Hub integration (`ADAPTIVE-WP-0001`) wires agent orientation, workplan tracking, and custodian brief sync. @@ -38,4 +40,4 @@ adapting, and implementing pricing models across the product lifecycle. See - Agent instructions: `AGENTS.md` - Workplans: `workplans/` - Coulomb MVP artifacts: `projects/coulomb-pricing/` -- Offline hub brief: `.custodian-brief.md` \ No newline at end of file +- Offline hub brief: `.custodian-brief.md` diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml index f944e47..c174d8d 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,4 +1,4 @@ version: 1 -updated: '2026-06-16' -domain: helix_forge +updated: '2026-07-02' +domain: financials capabilities: [] diff --git a/workplans/ADAPTIVE-WP-0001-statehub-bootstrap.md b/workplans/ADAPTIVE-WP-0001-statehub-bootstrap.md index 69364b7..906d9ef 100644 --- a/workplans/ADAPTIVE-WP-0001-statehub-bootstrap.md +++ b/workplans/ADAPTIVE-WP-0001-statehub-bootstrap.md @@ -2,13 +2,13 @@ id: ADAPTIVE-WP-0001 type: workplan title: "Bootstrap State Hub integration" -domain: helix_forge +domain: financials repo: adaptive-pricing status: finished owner: codex topic_slug: helix-forge created: "2026-06-21" -updated: "2026-06-21" +updated: "2026-07-02" state_hub_workstream_id: "d1e43a74-0c17-4403-9f7c-3feea527b161" --- @@ -65,4 +65,4 @@ legacy `AdaptivePricing-MVP-Workplan.md`. After workplan file updates, run from ```bash make fix-consistency REPO=adaptive-pricing -``` \ No newline at end of file +``` diff --git a/workplans/ADHOC-2026-07-02.md b/workplans/ADHOC-2026-07-02.md new file mode 100644 index 0000000..513c80f --- /dev/null +++ b/workplans/ADHOC-2026-07-02.md @@ -0,0 +1,29 @@ +--- +id: ADHOC-2026-07-02 +type: workplan +title: "Ad hoc repo consistency cleanup - 2026-07-02" +domain: financials +repo: adaptive-pricing +status: finished +owner: codex +topic_slug: helix-forge +created: "2026-07-02" +updated: "2026-07-02" +state_hub_workstream_id: "1c913a82-81b5-4051-aa28-ddc50af592cf" +--- + +# Ad hoc repo consistency cleanup - 2026-07-02 + +## Normalize Repo Metadata And Status Docs + +```task +id: ADHOC-2026-07-02-T01 +status: done +priority: medium +state_hub_task_id: "1b6ac899-a8d3-411d-b012-8a3fc98466b1" +``` + +Align repo-managed metadata with the primary `financials` classification while +keeping the State Hub topic mapping explicit (`helix-forge`). Refresh stale +root status text and fill the remaining Claude rule placeholders with the +actual repo architecture, workflow, and boundary notes. diff --git a/workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md b/workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md index ec7cf71..5489156 100644 --- a/workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md +++ b/workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md @@ -2,13 +2,13 @@ id: ADAPTIVE-WP-0002 type: workplan title: "Economic Observatory MVP (Coulomb Social)" -domain: helix_forge +domain: financials repo: adaptive-pricing status: finished owner: codex topic_slug: helix-forge created: "2026-06-21" -updated: "2026-06-22" +updated: "2026-07-02" state_hub_workstream_id: "9e0b7784-702a-4bc7-b7a1-3ff801f9c768" --- @@ -208,4 +208,4 @@ state_hub_task_id: "563cbded-ad2a-4ee8-8779-18f7e55970df" Cost floor, value range, and market price observatory views. Done 2026-06-22: `observatory/pricing_context.py`, `data/value_range.json`, -`data/market_signals.json`, wired into UI and API. \ No newline at end of file +`data/market_signals.json`, wired into UI and API.