Complete fin-hub repo integration (FIN-WP-0000)
Link the DB-first onboarding workstream to FIN-WP-0000-repo-integration.md, finish agent orientation (rules stubs, remove first-session), add repo classification, and close all four custodian onboarding tasks.
This commit is contained in:
parent
a0341ba35f
commit
7e53c21feb
10 changed files with 145 additions and 94 deletions
|
|
@ -1,8 +1,29 @@
|
|||
## Architecture
|
||||
|
||||
<!-- TODO: Describe the key design decisions and component structure.
|
||||
Key modules, data flows, external integrations, state machines, etc. -->
|
||||
Fin-hub extends `hub-core` with financial models and operator surfaces. Generic
|
||||
hub primitives (domains, repos, messages, progress) come from hub-core;
|
||||
fin-specific models and services live here.
|
||||
|
||||
### Modules
|
||||
|
||||
| Module | Role |
|
||||
|--------|------|
|
||||
| `models/` | Budget, commitment, service cost, burn rate dataclasses |
|
||||
| `ingest/` | CSV parsers for cloud, Anthropic billing, HostEurope invoices |
|
||||
| `services/runway.py` | Runway projection from balance + monthly burn series |
|
||||
| `services/alerts.py` | Threshold evaluation (runway months, budget overrun) |
|
||||
| `coupling/` | FOS §9 signals: fin→dev (resource pressure), fin→ops (cost attribution), fin→canon (viability) |
|
||||
| `cli.py` | Operator CLI (`finhub` entrypoint) |
|
||||
|
||||
### Data flow
|
||||
|
||||
```
|
||||
CSV exports → ingest parsers → cost models → runway/alerts → coupling emit → State Hub progress
|
||||
```
|
||||
|
||||
v0.1 is manual CSV import only. Persistent ledger and HTTP read surface are
|
||||
tracked in `FIN-WP-0001`.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
|
||||
`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
## First Session Protocol
|
||||
|
||||
Triggered when `get_domain_summary("infotech")` shows **no workplans**.
|
||||
The project is registered but work has not yet been structured.
|
||||
|
||||
**Step 1 — Read, don't write**
|
||||
- `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope
|
||||
- `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases
|
||||
- Scan repo root: README, directory structure, existing code or docs
|
||||
|
||||
**Step 2 — Survey in-progress work**
|
||||
Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
|
||||
|
||||
**Step 3 — Propose workplans to Bernd**
|
||||
Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
|
||||
roadmap phase. **Wait for approval before creating.**
|
||||
|
||||
**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
|
||||
```
|
||||
workplans/FIN-WP-NNNN-<slug>.md ← write this, commit it
|
||||
```
|
||||
Then register by running the consistency check — do **not** call
|
||||
`create_workplan`/`create_task` yourself; manual registration duplicates what
|
||||
C-06 creates from the file:
|
||||
```bash
|
||||
statehub fix-consistency --repo fin-hub
|
||||
```
|
||||
C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
|
||||
(legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
|
||||
back into the file.
|
||||
|
||||
**Step 5 — Record the setup**
|
||||
```
|
||||
add_progress_event(
|
||||
summary="First session: structured infotech into N workplans, M tasks",
|
||||
event_type="milestone",
|
||||
topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
|
||||
detail={"workplans": [...], "tasks_created": M}
|
||||
)
|
||||
```
|
||||
|
||||
<!-- Delete or archive this file once past first session -->
|
||||
|
|
@ -2,7 +2,9 @@
|
|||
|
||||
This repo owns **fin-hub** only. It does not own:
|
||||
|
||||
<!-- TODO: List what belongs in adjacent repos, e.g.:
|
||||
- SSH key management → railiance-infra/
|
||||
- State hub code → state-hub/
|
||||
-->
|
||||
- State Hub API / MCP server → `state-hub/`
|
||||
- Generic hub router factories and models → `hub-core/`
|
||||
- Payment execution, invoicing, banking → out of scope (see `SCOPE.md`)
|
||||
- Business canon and bootstrap protocol → `the-custodian/canon/`
|
||||
- Core Hub ops evidence lane → `core-hub/`
|
||||
- SSH tunnel lifecycle → `ops-bridge/`
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
**Purpose:** fin-hub - (fill in purpose)
|
||||
**Purpose:** Financial Allocator hub for the FOS federation — budgets, burn rate, runway projection, and cross-hub viability signals.
|
||||
|
||||
**Domain:** infotech
|
||||
**Repo slug:** fin-hub
|
||||
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
|
||||
**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
|
||||
|
|
@ -1,19 +1,26 @@
|
|||
## Stack
|
||||
|
||||
<!-- TODO: Fill in language, frameworks, and key dependencies -->
|
||||
- **Language:**
|
||||
- **Key deps:**
|
||||
- **Language:** Python 3.12+
|
||||
- **Package manager:** uv
|
||||
- **Key deps:** hub-core (generic hub primitives), pydantic, httpx
|
||||
|
||||
## Dev Commands
|
||||
|
||||
```bash
|
||||
# TODO: Fill in the standard commands for this repo
|
||||
|
||||
# Install dependencies
|
||||
uv sync
|
||||
|
||||
# Run tests
|
||||
uv run pytest
|
||||
|
||||
# Lint / type check
|
||||
# CLI — runway projection
|
||||
uv run finhub runway --balance 12000 --monthly-burn 2100,2200,2000
|
||||
|
||||
# Build / package (if applicable)
|
||||
```
|
||||
# CLI — import cost CSVs
|
||||
uv run finhub import-cloud tests/fixtures/cloud-costs.csv
|
||||
uv run finhub import-anthropic tests/fixtures/anthropic-billing.csv
|
||||
uv run finhub import-hosteurope tests/fixtures/hosteurope.csv
|
||||
|
||||
# CLI — emit cross-hub signals (requires STATE_HUB_API)
|
||||
uv run finhub runway --balance 12000 --monthly-burn 2100 --emit
|
||||
```
|
||||
24
.repo-classification.yaml
Normal file
24
.repo-classification.yaml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
# Repo classification (Repo Classification Standard v1.0).
|
||||
|
||||
repo_classification:
|
||||
standard: Repo Classification Standard
|
||||
version: '1.0'
|
||||
classified_at: '2026-07-08'
|
||||
classified_by: human
|
||||
category: tooling
|
||||
domain: infotech
|
||||
secondary_domains:
|
||||
- financials
|
||||
capability_tags:
|
||||
- platform
|
||||
- observability
|
||||
- orchestration
|
||||
business_stake:
|
||||
- technology
|
||||
- execution
|
||||
- operations
|
||||
business_mechanics:
|
||||
- operation
|
||||
- control
|
||||
notes: Financial Allocator hub for the FOS federation — budgets, burn rate,
|
||||
runway projection, and cross-hub viability signals. product-as-component.
|
||||
|
|
@ -1,32 +0,0 @@
|
|||
<!--
|
||||
CUSTODIAN SUGGESTION — generated by `custodian register-project`
|
||||
|
||||
This file was written by the Custodian State Hub registration workflow.
|
||||
It contains the standard State Hub integration block for this repository.
|
||||
|
||||
A Claude Code agent in this repo should:
|
||||
1. Read this file and the existing CLAUDE.md side by side
|
||||
2. Integrate the sections below into CLAUDE.md — preserve all existing
|
||||
project-specific conventions; add or update the hub integration block
|
||||
3. Delete this file once integration is complete and commit the result
|
||||
|
||||
Do NOT add this file to .gitignore. It is a temporary artefact that signals
|
||||
pending integration work to the repo agent.
|
||||
-->
|
||||
|
||||
# DEPRECATED — see project_rules/
|
||||
|
||||
This file was the monolithic CLAUDE.md template. It has been replaced by the
|
||||
modular @-import structure in `scripts/project_rules/`.
|
||||
|
||||
`register_project.sh` now generates:
|
||||
- `CLAUDE.md` — thin @-import index (9 lines)
|
||||
- `.claude/rules/repo-identity.md` — purpose, domain, slug, topic ID
|
||||
- `.claude/rules/session-protocol.md`— orient → inbox → workplans → brief
|
||||
- `.claude/rules/first-session.md` — bootstrap flow (delete once past FSP)
|
||||
- `.claude/rules/workplan-convention.md` — prefix, location, delegates to global
|
||||
- `.claude/rules/stack-and-commands.md` — language, deps, dev commands (stub)
|
||||
- `.claude/rules/architecture.md` — design overview (stub)
|
||||
- `.claude/rules/repo-boundary.md` — what this repo does NOT own (stub)
|
||||
|
||||
See `ops-bridge/.claude/` for a complete reference example.
|
||||
|
|
@ -3,7 +3,6 @@
|
|||
@SCOPE.md
|
||||
@.claude/rules/repo-identity.md
|
||||
@.claude/rules/session-protocol.md
|
||||
@.claude/rules/first-session.md
|
||||
@.claude/rules/workplan-convention.md
|
||||
@.claude/rules/stack-and-commands.md
|
||||
@.claude/rules/architecture.md
|
||||
|
|
|
|||
|
|
@ -10,8 +10,9 @@ here.
|
|||
|
||||
## Status
|
||||
|
||||
Bootstrap scaffold (`CUST-WP-0025-T22`). Models and ingestion pipelines are
|
||||
tracked in `CUST-WP-0025-T23`–`T24`.
|
||||
MVP complete (`CUST-WP-0025` T22–T26): models, CSV ingest, runway CLI, FOS
|
||||
coupling, RaaS packaging draft. Operational hardening tracked in
|
||||
`workplans/FIN-WP-0001-runway-operations-lane.md`.
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
|
|||
71
workplans/FIN-WP-0000-repo-integration.md
Normal file
71
workplans/FIN-WP-0000-repo-integration.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
id: FIN-WP-0000
|
||||
type: workplan
|
||||
title: "Repo Integration: fin-hub"
|
||||
domain: infotech
|
||||
repo: fin-hub
|
||||
status: finished
|
||||
owner: fin-hub
|
||||
topic_slug: infotech
|
||||
created: "2026-07-07"
|
||||
updated: "2026-07-08"
|
||||
state_hub_workstream_slug: "repo-integration-fin-hub"
|
||||
state_hub_workstream_id: "dd9ba4cc-835a-4b92-9d13-bd68c8683359"
|
||||
note: >
|
||||
DB-first bootstrap workstream created by custodian register-project. This file
|
||||
retroactively satisfies ADR-001 (C-07). Primary ongoing work continues in
|
||||
FIN-WP-0001 after onboarding closes.
|
||||
---
|
||||
|
||||
# FIN-WP-0000 — Repo Integration: fin-hub
|
||||
|
||||
Bootstrapping workstream for `fin-hub` registration under the `infotech` domain.
|
||||
Closes once agent orientation, the first operational workplan, SBOM, and EP/TD
|
||||
catalogue are in place.
|
||||
|
||||
## Integrate CLAUDE.custodian.md → CLAUDE.md
|
||||
|
||||
```task
|
||||
id: FIN-WP-0000-T01
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "01a71848-1649-484b-96ed-ca12f281cd22"
|
||||
```
|
||||
|
||||
Merge the custodian suggestion into the modular `@.claude/rules/` structure,
|
||||
fill orientation stubs, and delete `CLAUDE.custodian.md`.
|
||||
|
||||
## Write first workplan and initialise workplans/
|
||||
|
||||
```task
|
||||
id: FIN-WP-0000-T02
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "9a35240f-d1b5-4288-8f4d-f3986c97636c"
|
||||
```
|
||||
|
||||
Create `workplans/FIN-WP-0001-runway-operations-lane.md` covering post-MVP
|
||||
operational hardening and federation evidence.
|
||||
|
||||
## Ingest SBOM
|
||||
|
||||
```task
|
||||
id: FIN-WP-0000-T03
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "3ec434d7-fd74-41ff-a792-048ec5b2788f"
|
||||
```
|
||||
|
||||
Capture dependency snapshot via `make ingest-sbom REPO=fin-hub SCAN=1
|
||||
REPO_PATH=/home/worsch/fin-hub` from the state-hub directory.
|
||||
|
||||
## Register known EPs and TDs
|
||||
|
||||
```task
|
||||
id: FIN-WP-0000-T04
|
||||
status: done
|
||||
priority: low
|
||||
state_hub_task_id: "fa4a24fb-5e16-4917-850b-6d082ec8ff9d"
|
||||
```
|
||||
|
||||
Register extension points and technical debt discovered during onboarding.
|
||||
Loading…
Add table
Add a link
Reference in a new issue