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

Normalize repo metadata and sync docs

Browse Source
This commit is contained in:
codex
2026-07-02 10:21:02 +02:00
parent 0a38def5a5
commit 327d3c551b
13 changed files with 182 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
.claude/rules/architecture.md
View File

@@ -1,7 +1,37 @@
## Architecture ## Architecture
<!-- TODO: Describe the key design decisions and component structure. The repo has two layers:
Key modules, data flows, external integrations, state machines, etc. -->
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 ## Quick Reference

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

@@ -1,8 +1,12 @@
## Repo boundary ## Repo boundary
This repo owns **adaptive-pricing** only. It does not own: This repo owns **adaptive-pricing** only. It does not own:
- State Hub server code, DB schema, or consistency tooling → `~/state-hub`
<!-- TODO: List what belongs in adjacent repos, e.g.: - SSH certificates, login flows, or secret vending → `ops-warden`,
- SSH key management → railiance-infra/ `ops-bridge`, OpenBao, Keycloak, and related custody systems
- State hub code → state-hub/ - 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/`

5
.claude/rules/repo-identity.md
View File

@@ -2,4 +2,9 @@
**Domain:** financials **Domain:** financials
**Repo slug:** adaptive-pricing **Repo slug:** adaptive-pricing
**State Hub topic:** helix-forge
**Topic ID:** f39fa2a3-c491-414c-a91b-b4c5fcc6139c **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

16
.claude/rules/session-protocol.md
View File

@@ -13,6 +13,8 @@ Then call the MCP tool for richer cross-domain context when MCP tools are expose
``` ```
get_domain_summary("financials") 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: If MCP tools are unavailable in the current agent session, use the REST API:
```bash ```bash
curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool 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** **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 2. **Pending tasks** from `workplans/` + any `[repo:adaptive-pricing]` hub tasks
3. **Goal guidance** — if `goal_guidance` in summary: 3. **Goal guidance** — if `goal_guidance` in summary:
- `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* - `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: If workplan files were modified, ensure the local copy is up to date first:
```bash ```bash
git -C <repo_path> pull --ff-only git -C <repo_path> 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), Fallback when the CLI is unavailable:
use the combined target which pulls before fixing:
```bash ```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 **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 will sync the file to match DB. **C-16** (repo behind remote) blocks all writes

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

@@ -1,19 +1,28 @@
## Stack ## Stack
<!-- TODO: Fill in language, frameworks, and key dependencies --> - **Language:** Markdown-heavy repo with a Python 3 implementation subtree
- **Language:** - **Key deps:** Python stdlib for the observatory runtime, `pytest` for tests,
- **Key deps:** optional `make` for wrappers, whynot-design vendored UI assets in
`projects/coulomb-pricing/ui/vendor/`
## Dev Commands ## Dev Commands
```bash ```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 # UI vendor refresh
make design
# Build / package (if applicable)
``` ```

6
.custodian-brief.md
View File

@@ -1,8 +1,8 @@
<!-- custodian-brief: generated by fix-consistency — do not edit manually --> <!-- custodian-brief: generated by fix-consistency — do not edit manually -->
# Custodian Brief — adaptive-pricing # Custodian Brief — adaptive-pricing
**Domain:** infotech **Domain:** financials
**Last synced:** 2026-06-22 21:23 UTC **Last synced:** 2026-07-02 08:19 UTC
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* **State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
## Active Workstreams ## Active Workstreams
@@ -13,6 +13,6 @@
## MCP Orientation (when available) ## MCP Orientation (when available)
If the state-hub MCP server is reachable, call: If the state-hub MCP server is reachable, call:
`get_domain_summary("infotech")` `get_domain_summary("financials")`
This provides richer cross-domain context. This provides richer cross-domain context.
If the MCP call fails, use this file as your orientation source. If the MCP call fails, use this file as your orientation source.

68
AGENTS.md
View File

@@ -4,11 +4,17 @@
**Purpose:** Auto-regulating market value exploring price engine. **Purpose:** Auto-regulating market value exploring price engine.
**Domain:** financials **Primary repo domain:** financials
**Repo slug:** adaptive-pricing **Repo slug:** adaptive-pricing
**State Hub topic:** `helix-forge`
**Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c` **Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
**Workplan prefix:** `ADAPTIVE-WP-` **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 ## State Hub Integration
@@ -27,7 +33,7 @@ there is no MCP server for Codex agents.
# Offline brief — works without hub connection # Offline brief — works without hub connection
cat .custodian-brief.md 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" \ curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \
| python3 -m json.tool | python3 -m json.tool
@@ -80,7 +86,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
## Session Protocol ## Session Protocol
**Start:** **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 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 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` 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/<task_id>" \
**Close:** **Close:**
1. Update workplan file task statuses to reflect progress 1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed 2. Log: `POST /progress/` with a summary of what changed
3. Note for the custodian operator: after workplan file changes, run from 3. After workplan file changes, run:
`~/state-hub`:
```bash ```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 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 | | Path | Purpose |
|------|---------| |------|---------|
| `INTENT.md`, `docs/`, `research/`, `registry/` | Generic adaptive-pricing framework | | `INTENT.md`, `docs/`, `research/`, `registry/` | Generic adaptive-pricing framework |
| `projects/<slug>/` | Deployment-specific MVP material (integrations, configs, project docs) | | `projects/<slug>/` | Deployment-specific implementations, integrations, data, and project docs |
| `workplans/` | ADR-001 workplans and task tracking (including MVP execution plans) | | `workplans/` | ADR-001 workplans and task tracking (including MVP execution plans) |
Do not place project-specific MVP documentation in `specs/` or other generic 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 Coulomb MVP workplan is archived at
`workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md`. `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) ## Workplan Convention (ADR-001)
@@ -194,11 +239,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
id: ADAPTIVE-WP-NNNN id: ADAPTIVE-WP-NNNN
type: workplan type: workplan
title: "..." title: "..."
domain: helix_forge domain: financials
repo: adaptive-pricing repo: adaptive-pricing
status: proposed | ready | active | blocked | backlog | finished | archived status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex owner: codex
topic_slug: ... topic_slug: helix-forge
created: "YYYY-MM-DD" created: "YYYY-MM-DD"
updated: "YYYY-MM-DD" updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit state_hub_workstream_id: "<uuid>" # 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: To create a new workplan:
1. Write the file following the format above 1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=adaptive-pricing` 2. Run `statehub fix-consistency` locally; use the direct CLI fallback above if
(or send a message to the hub agent via `POST /messages/`) `statehub` is not installed. Ask the operator only if the CLI or State Hub
API is unavailable.

7
README.md
View File

@@ -18,6 +18,7 @@ pricing to payment-provider execution.
## Status ## Status
Early framework phase (documentation and research). First implementation: Framework-first repo with one finished project-specific implementation:
[Economic Observatory MVP](workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md) (finished) [Economic Observatory MVP](workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md)
for Coulomb Social. for Coulomb Social. The root remains the generic pricing framework; the current
runtime lives under `projects/coulomb-pricing/observatory/`.

8
SCOPE.md
View File

@@ -25,9 +25,11 @@ adapting, and implementing pricing models across the product lifecycle. See
## Current State ## Current State
- **Phase:** early framework — documentation, research, and registry scaffolding. - **Phase:** framework plus first project deployment — root docs/research remain
- **Runtime:** none in this repo yet; first implementation is the Coulomb Social generic, while Coulomb Social provides the first concrete implementation.
Economic Observatory MVP (`ADAPTIVE-WP-0002`). - **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, - **Bootstrap:** State Hub integration (`ADAPTIVE-WP-0001`) wires agent orientation,
workplan tracking, and custodian brief sync. workplan tracking, and custodian brief sync.

4
registry/indexes/capabilities.yaml
View File

@@ -1,4 +1,4 @@
version: 1 version: 1
updated: '2026-06-16' updated: '2026-07-02'
domain: helix_forge domain: financials
capabilities: [] capabilities: []

4
workplans/ADAPTIVE-WP-0001-statehub-bootstrap.md
View File

@@ -2,13 +2,13 @@
id: ADAPTIVE-WP-0001 id: ADAPTIVE-WP-0001
type: workplan type: workplan
title: "Bootstrap State Hub integration" title: "Bootstrap State Hub integration"
domain: helix_forge domain: financials
repo: adaptive-pricing repo: adaptive-pricing
status: finished status: finished
owner: codex owner: codex
topic_slug: helix-forge topic_slug: helix-forge
created: "2026-06-21" created: "2026-06-21"
updated: "2026-06-21" updated: "2026-07-02"
state_hub_workstream_id: "d1e43a74-0c17-4403-9f7c-3feea527b161" state_hub_workstream_id: "d1e43a74-0c17-4403-9f7c-3feea527b161"
--- ---

29
workplans/ADHOC-2026-07-02.md Normal file
View File

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

4
workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md
View File

@@ -2,13 +2,13 @@
id: ADAPTIVE-WP-0002 id: ADAPTIVE-WP-0002
type: workplan type: workplan
title: "Economic Observatory MVP (Coulomb Social)" title: "Economic Observatory MVP (Coulomb Social)"
domain: helix_forge domain: financials
repo: adaptive-pricing repo: adaptive-pricing
status: finished status: finished
owner: codex owner: codex
topic_slug: helix-forge topic_slug: helix-forge
created: "2026-06-21" created: "2026-06-21"
updated: "2026-06-22" updated: "2026-07-02"
state_hub_workstream_id: "9e0b7784-702a-4bc7-b7a1-3ff801f9c768" state_hub_workstream_id: "9e0b7784-702a-4bc7-b7a1-3ff801f9c768"
--- ---