diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md new file mode 100644 index 0000000..0e8a5d9 --- /dev/null +++ b/.claude/rules/agents.md @@ -0,0 +1,20 @@ +## Kaizen Agents + +Specialized agent personas available on demand via the state-hub MCP. + +**Discover:** `list_kaizen_agents()` — returns all agents with name, description, category +**Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them + +Common agents: + +| Agent | Category | When to use | +|-------|----------|-------------| +| `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature | +| `code-refactoring` | quality | Code quality analysis and safe refactoring | +| `test-maintenance` | testing | Diagnose and fix failing tests | +| `requirements-engineering` | process | Prevent interface/mock mismatches upfront | +| `keepaTodofile` | process | Maintain TODO.md during work | +| `project-management` | process | Track status, determine next steps | +| `datamodel-optimization` | quality | Optimize dataclasses and data structures | + +All 17 agents: call `list_kaizen_agents()` for the full list. diff --git a/.claude/rules/architecture.md b/.claude/rules/architecture.md new file mode 100644 index 0000000..7c2a645 --- /dev/null +++ b/.claude/rules/architecture.md @@ -0,0 +1,8 @@ +## Architecture + + + +## Quick Reference + +`~/state-hub/mcp_server/TOOLS.md` — MCP tool reference diff --git a/.claude/rules/credential-routing.md b/.claude/rules/credential-routing.md new file mode 100644 index 0000000..b9c8fc5 --- /dev/null +++ b/.claude/rules/credential-routing.md @@ -0,0 +1,50 @@ +# 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 "" --json +warden route show --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=vantage-point` 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` \ No newline at end of file diff --git a/.claude/rules/first-session.md b/.claude/rules/first-session.md new file mode 100644 index 0000000..24046ad --- /dev/null +++ b/.claude/rules/first-session.md @@ -0,0 +1,38 @@ +## First Session Protocol + +Triggered when `get_domain_summary("infotech")` shows **no workstreams**. +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 workstreams to Bernd** +Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a +roadmap phase. **Wait for approval before creating.** + +**Step 4 — Create workplan file first, then DB record (ADR-001)** +``` +workplans/VANTAGE-WP-NNNN-.md ← write this first +``` +Then register in the hub: +``` +create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...") +create_task(workstream_id="", title="...", priority="high|medium|low") +``` + +**Step 5 — Record the setup** +``` +add_progress_event( + summary="First session: structured infotech into N workstreams, M tasks", + event_type="milestone", + topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", + detail={"workstreams": [...], "tasks_created": M} +) +``` + + diff --git a/.claude/rules/repo-boundary.md b/.claude/rules/repo-boundary.md new file mode 100644 index 0000000..1270237 --- /dev/null +++ b/.claude/rules/repo-boundary.md @@ -0,0 +1,8 @@ +## Repo boundary + +This repo owns **Vantage Point** only. It does not own: + + diff --git a/.claude/rules/repo-identity.md b/.claude/rules/repo-identity.md new file mode 100644 index 0000000..1bf15e8 --- /dev/null +++ b/.claude/rules/repo-identity.md @@ -0,0 +1,5 @@ +**Purpose:** Vantage Point - (fill in purpose) + +**Domain:** infotech +**Repo slug:** vantage-point +**Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a diff --git a/.claude/rules/session-protocol.md b/.claude/rules/session-protocol.md new file mode 100644 index 0000000..8379e29 --- /dev/null +++ b/.claude/rules/session-protocol.md @@ -0,0 +1,85 @@ +## Session Protocol + +Dev Hub (State Hub API): http://127.0.0.1:8000 +MCP server name in `~/.claude.json`: `dev-hub` + +**Step 1 — Orient** + +Read the offline-safe brief first — it works without a live hub connection: +```bash +cat .custodian-brief.md +``` +Then call the MCP tool for richer cross-domain context when MCP tools are exposed: +``` +get_domain_summary("infotech") +``` +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 +``` +If the hub is offline: `cd ~/state-hub && make api` + +**Step 2 — Check inbox** +With MCP tools: +``` +get_messages(to_agent="vantage-point", unread_only=True) +``` +Mark read with `mark_message_read(message_id)`. Reply or act on coordination +requests before proceeding. + +Without MCP tools: +```bash +curl -s "http://127.0.0.1:8000/messages/?to_agent=vantage-point&unread_only=true" \ + | python3 -m json.tool +curl -s -X PATCH "http://127.0.0.1:8000/messages//read" \ + -H "Content-Type: application/json" -d '{}' +``` + +**Step 3 — Scan workplans** +```bash +ls workplans/ +``` +For each file with `status: ready`, `active`, or `blocked`, note pending +`wait`/`todo`/`progress` tasks. + +**Step 4 — Present brief** + +1. **Active workstreams** for `infotech` — title, task counts, blocking decisions +2. **Pending tasks** from `workplans/` + any `[repo:vantage-point]` hub tasks +3. **Goal guidance** — if `goal_guidance` in summary: + - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"* + - `alignment_warnings`: flag if active work is not aligned with current goal +4. **Suggested next action** — highest-priority open item +5. **SBOM status** — flag if `last_sbom_at` is unset for this repo + +If no workstreams: follow First Session Protocol (`first-session.md`). + +**During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()` + +> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`) +> are First Session Protocol only. Work structure belongs in repo files (ADR-001). + +**Session close:** +With MCP tools: +``` +add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="") +``` +Without MCP tools: +```bash +curl -s -X POST http://127.0.0.1:8000/progress/ \ + -H "Content-Type: application/json" \ + -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"","event_type":"note","summary":"what changed","author":"codex"}' +``` +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=vantage-point +``` +For repos where implementation runs on a remote machine (e.g. CoulombCore), +use the combined target which pulls before fixing: +```bash +cd ~/state-hub && make fix-consistency-remote REPO=vantage-point +``` +**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 +until you pull — intentional to prevent clobbering remote progress. diff --git a/.claude/rules/stack-and-commands.md b/.claude/rules/stack-and-commands.md new file mode 100644 index 0000000..6d2a123 --- /dev/null +++ b/.claude/rules/stack-and-commands.md @@ -0,0 +1,20 @@ +## Stack + +- **Language:** Markdown-first registry and planning repo (no application runtime yet) +- **Key deps:** State Hub ADR-001 workplans, `registry/indexes/capabilities.yaml` + +## Dev Commands + +```bash +# Orient (offline-safe) +cat .custodian-brief.md +cat INTENT.md +cat SCOPE.md +ls workplans/ + +# After workplan or registry edits — from ~/state-hub +make fix-consistency REPO=vantage-point + +# Sanity-check markdown / registry edits +git diff --check +``` diff --git a/.claude/rules/workplan-convention.md b/.claude/rules/workplan-convention.md new file mode 100644 index 0000000..f593791 --- /dev/null +++ b/.claude/rules/workplan-convention.md @@ -0,0 +1,40 @@ +## Workplan Convention (ADR-001) + +File location: `workplans/VANTAGE-WP-NNNN-.md` +ID prefix: `VANTAGE-WP-` + +Work items originate as files in this repo **before** being registered in the hub. + +Canonical workplan/workstream frontmatter statuses are: +`proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`. +Use `proposed` for a newly drafted plan, `ready` after review against current +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-VANTAGE-WP-NNNN-.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**: +`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids +`ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed +directly. Promote anything requiring analysis, design, approval, dependencies, or +multiple planned phases into a normal workplan. + +Ecosystem todos from other agents arrive as `[repo:vantage-point]` hub tasks — +visible at session start. Pick one up by creating the workplan file, then registering +the workstream. + +Task blocks use this shape: + +```task +id: VANTAGE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # written by fix-consistency — do not edit +``` + +Status progression is `todo` → `progress` → `done`; use `wait` for waiting or +blocked work and `cancel` for stopped work. + + diff --git a/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..613236e --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,18 @@ + +# Custodian Brief — vantage-point + +**Domain:** infotech +**Last synced:** 2026-06-24 16:24 UTC +**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)* + +## Active Workstreams + +*(none — repo may need first-session setup)* + +--- +## MCP Orientation (when available) + +If the state-hub MCP server is reachable, call: +`get_domain_summary("infotech")` +This provides richer cross-domain context. +If the MCP call fails, use this file as your orientation source. diff --git a/.forgejo/workflows/ci-smoke.yaml b/.forgejo/workflows/ci-smoke.yaml new file mode 100644 index 0000000..bd44c56 --- /dev/null +++ b/.forgejo/workflows/ci-smoke.yaml @@ -0,0 +1,29 @@ +# Canonical CI smoke template (tier 1 routing drill). +# Copy to: .forgejo/workflows/ci-smoke.yaml in consumer repos. +name: CI Smoke + +on: + push: + branches: + - main + workflow_dispatch: + +jobs: + host-smoke: + runs-on: self-hosted + steps: + - name: Routing probe (host runner) + run: | + set -eu + echo "repository=${GITHUB_REPOSITORY:-unknown}" + echo "sha=${GITHUB_SHA:-unknown}" + echo "runner=${RUNNER_NAME:-unknown}" + uname -a + + container-smoke: + runs-on: ubuntu-latest + steps: + - name: Routing probe (container label) + run: | + set -eu + echo "container-smoke ok for ${GITHUB_REPOSITORY:-unknown}" \ No newline at end of file diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..87784cd --- /dev/null +++ b/.repo-classification.yaml @@ -0,0 +1,21 @@ +repo_classification: + standard: Repo Classification Standard + version: '1.0' + classified_at: '2026-06-22' + classified_by: agent + category: research + domain: infotech + secondary_domains: [] + capability_tags: + - knowledge + - analytics + - platform + - documentation + business_stake: + - technology + - intelligence + - product + business_mechanics: + - intention + - adaptation + notes: Network-based graph model exploration and dependency reasoning framework. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7ac0794 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,219 @@ +# Vantage Point — Agent Instructions + +## Repo Identity + +**Purpose:** Vantage Point - (fill in purpose) + +**Domain:** infotech +**Repo slug:** vantage-point +**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a` +**Workplan prefix:** `VANTAGE-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=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=vantage-point&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//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": "", + "task_id": "" + }' +``` + +Omit `workstream_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -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/" \ + -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=vantage-point&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=vantage-point + ``` + 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 "" --json +warden route show --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=vantage-point` 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` + + + + +--- + +## 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/VANTAGE-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-VANTAGE-WP-NNNN-.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: VANTAGE-WP-NNNN +type: workplan +title: "..." +domain: infotech +repo: vantage-point +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # 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: VANTAGE-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # 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=vantage-point` + (or send a message to the hub agent via `POST /messages/`) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..da62965 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,12 @@ +# Vantage Point — Claude Code Instructions + +@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 +@.claude/rules/repo-boundary.md +@.claude/rules/credential-routing.md +@.claude/rules/agents.md diff --git a/README.md b/README.md index fcd7b8f..0e27c33 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,37 @@ -# repo-seed +# vantage-point -A git repository template to bootstrap coulomb projects from. \ No newline at end of file +Generic system for exploring, analyzing, and reasoning about dependency +structures across arbitrary domains, treated as **Network-Based Graph +Models (NBGM)** — typed graphs of entities (nodes) and relationships +(edges) enriched with attributes, provenance, and semantics. + +Vantage Point is a **multi-perspective exploration environment**: the same +underlying graph can be viewed from different "vantage points" to answer +domain-specific questions, rather than binding one fixed visualization or +domain vocabulary to the model. The vocabulary is grounded in Tamara +Munzner's nested design model and the NBGM framing from Meyer, Sedlmair, +and Munzner (BELIV 2012). + +## Status + +**Specification stage — no implementation yet.** `docs/nbgm-spec-v0.1.md` +is a substantial (670-line) draft baseline defining core identity/typing +rules for nodes and edges, the attribute model and namespaces, provenance +and lineage, a baseline catalog of inspection operations, and alignment +notes for repo-native graph bindings (e.g. Railiance Fabric). Storage +engines, query languages, visualization encodings, and domain-specific +type catalogs are explicitly out of scope for v0.1. + +## Getting oriented + +- **Intent:** `INTENT.md` — full rationale and grounding in the NBGM + research literature +- **Scope and boundaries:** `SCOPE.md` +- **The spec:** `docs/nbgm-spec-v0.1.md` +- **Build history:** `workplans/` + +## In scope + +NBGM specs, registry, and exploratory docs; State Hub workplans for graph +exploration features; alignment with `repo-scoping` and `railiance-fabric` +graph models. See `SCOPE.md` for the full in/out-of-scope breakdown. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..e1041e6 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,31 @@ +# SCOPE + +> Lightweight boundary for agents and contributors. + +--- + +## One-liner + +Generic system for exploring dependency structures as network-based graph models (NBGM). + +--- + +## Core Idea + +Vantage Point unifies entity/relationship inspection and reasoning across arbitrary domains. + +--- + +## In Scope + +- NBGM specs, registry, and exploratory docs +- State Hub workplans for graph exploration features +- Alignment with repo-scoping and fabric graph models + +--- + +## Out of Scope + +- Production graph database hosting +- Replacing railiance-fabric ingestion + diff --git a/docs/nbgm-spec-v0.1.md b/docs/nbgm-spec-v0.1.md new file mode 100644 index 0000000..25d553c --- /dev/null +++ b/docs/nbgm-spec-v0.1.md @@ -0,0 +1,671 @@ +# NBGM Specification v0.1 + +Network-Based Graph Model (NBGM) baseline for Vantage Point. + +**Status:** draft baseline +**Version:** `vantage.nbgm/v0.1` +**Related:** `INTENT.md`, `SCOPE.md` + +--- + +## 1. Purpose + +This document defines the domain-agnostic graph model that Vantage Point uses +to represent, inspect, and reason about dependency structures. + +An NBGM is a typed graph of entities (nodes) and relationships (edges) with +attributes and provenance. Meaning is not baked into the core model. Domains +attach interpretation through bindings, lenses, and vantage points. + +The vocabulary is grounded in Tamara Munzner's nested design model and the +Network-Based Graph Model framing in Meyer, Sedlmair, and Munzner +([BELIV 2012](https://miriah.github.io/publications/nbgm-beliv.pdf)). In that +framing, a **network** is a data-abstraction block: nodes, links, and +attributes are the structural primitives on which tasks, encodings, and +algorithms are stacked. + +### 1.1 Scope of v0.1 + +In scope: + +- core identity and typing rules for nodes and edges +- attribute model and namespaces +- provenance and lineage +- a baseline catalog of inspection operations +- alignment notes for repo-native graph bindings (for example Railiance Fabric) + +Out of scope for v0.1: + +- storage engines, query languages, or visualization encodings +- domain-specific node/edge type catalogs +- lens and vantage-point configuration schemas +- validation tooling and serialization formats (future workplans) + +### 1.2 Design principles + +1. **Neutral core, interpreted surface.** The model stores facts; bindings + supply domain semantics. +2. **Inspectable by default.** Every element should be explainable: what it + is, why it exists, and how it was derived. +3. **Provenance over assertion.** Observed and derived facts carry origin, + method, confidence, and freshness. +4. **Perspective-friendly structure.** The same graph supports multiple + inspection operations without duplicating source data. +5. **Composable bindings.** Repo-native declarations, scanners, and exports can + project into NBGM without becoming the authoring authority. + +--- + +## 2. Terminology + +| Term | Definition | +|------|------------| +| **Graph** | A bounded collection of nodes and edges sharing one identity and metadata envelope. | +| **Node** | An entity vertex with stable identity, kind, and attributes. | +| **Edge** | A directed or undirected relationship between two nodes. | +| **Kind** | A domain-defined type label for a node or edge (for example `Service`, `requires`). | +| **Attribute** | A named property on a node or edge, optionally typed and namespaced. | +| **Provenance** | Metadata describing how and when a fact entered the graph. | +| **Binding** | A domain projection that maps external declarations or observations into NBGM elements. | +| **Lens** | A named interpretation layer that selects, re-labels, or aggregates graph elements for a task. | +| **Vantage point** | A saved or ephemeral lens plus inspection context (focus, depth, filters). | +| **Inspection operation** | A read-only graph query or explanation primitive. | + +--- + +## 3. Graph envelope + +Every NBGM instance is wrapped in a graph envelope. + +```yaml +apiVersion: vantage.nbgm/v0.1 +kind: Graph +metadata: + id: example.ecosystem + title: Example ecosystem graph + domain: infotech # optional binding domain + created_at: "2026-06-24T00:00:00Z" + updated_at: "2026-06-24T00:00:00Z" + source_bindings: + - binding_id: railiance-fabric.export + source_ref: railiance-fabric/registry +spec: + node_count: 0 # informational; implementations may omit + edge_count: 0 + default_direction: directed +``` + +### 3.1 Required envelope fields + +| Field | Requirement | +|-------|-------------| +| `apiVersion` | Must be `vantage.nbgm/v0.1` for this revision. | +| `kind` | Must be `Graph`. | +| `metadata.id` | Stable graph identifier. Prefer dotted, lower-case slugs. | +| `metadata.title` | Human-readable graph name. | +| `metadata.updated_at` | ISO-8601 timestamp of last material change. | +| `spec.default_direction` | `directed` or `undirected`. Edge-level direction may override. | + +### 3.2 Optional envelope fields + +- `metadata.domain` — primary interpretation domain for the graph. +- `metadata.created_at` — first materialization time. +- `metadata.source_bindings[]` — list of bindings that produced or refreshed the graph. +- `metadata.labels` — arbitrary string tags for indexing and filtering. +- `metadata.description` — narrative summary of graph intent and coverage. + +--- + +## 4. Nodes + +A node represents one addressable entity in the modeled system. + +```yaml +kind: Node +metadata: + id: railiance-platform.openbao + stable_key: railiance-platform.openbao # durable id across renames + name: OpenBao + labels: + repo: railiance-platform + domain: railiance +spec: + node_kind: Service + lifecycle: active # planned | active | deprecated | retired + layer: service # optional stratification hint +attributes: + core: + description: Runtime secrets service + display: + label: OpenBao + visual_weight: 1.0 +provenance: + assertion_type: declared # declared | observed | derived | inferred + sources: + - ref: fabric/services/openbao.yaml + method: declaration_load + observed_at: "2026-06-24T00:00:00Z" + confidence: 1.0 + freshness_state: current # current | stale | unknown +``` + +### 4.1 Identity rules + +1. `metadata.id` is unique within a graph. +2. `metadata.stable_key` is optional but recommended when display ids may change. + Profile rules, deep links, and temporal comparison should prefer + `stable_key` when present. +3. IDs should be stable across re-ingestion when the underlying entity is + unchanged. Bindings must document their ID strategy. + +### 4.2 Required node fields + +| Field | Requirement | +|-------|-------------| +| `metadata.id` | Unique node identifier. | +| `spec.node_kind` | Domain-defined entity kind. | +| `provenance.assertion_type` | How the node fact was obtained. | +| `provenance.sources[]` | At least one source record for non-synthetic nodes. | + +### 4.3 Recommended node fields + +| Field | Purpose | +|-------|---------| +| `metadata.name` | Short display name. | +| `metadata.labels` | Cross-cutting indices (`repo`, `domain`, `environment`, etc.). | +| `spec.lifecycle` | Entity lifecycle state. | +| `spec.layer` | Layer or stratum for layout and filtering. | +| `attributes.core` | Domain-neutral or lightly-bound descriptive fields. | +| `provenance.confidence` | Numeric confidence in `[0, 1]`. | +| `provenance.freshness_state` | Whether the fact is current enough to trust for the active task. | + +### 4.4 Node kinds + +`spec.node_kind` is binding-defined. Vantage Point does not mandate a global +ontology in v0.1. Bindings should publish their kind catalog and mapping rules. + +Examples from existing ecosystem graphs: + +| Binding | Example node kinds | +|---------|-------------------| +| Railiance Fabric | `Repository`, `Service`, `Capability`, `Interface` | +| Repo-scoping | `Fact`, `Evidence`, `Feature`, `Capability`, `Ability`, `Scope` | + +Bindings may attach additional kind metadata under `attributes.binding.*` but +must not overload `spec.node_kind` with multiple meanings. + +--- + +## 5. Edges + +An edge represents a relationship between exactly two nodes. + +```yaml +kind: Edge +metadata: + id: railiance-platform.state-hub.requires.runtime-secrets + stable_key: railiance-platform.state-hub->runtime-secrets +spec: + edge_kind: requires + source_id: railiance-platform.state-hub + target_id: railiance-platform.openbao + direction: directed # directed | undirected + cardinality: many_to_one # optional: one_to_one | one_to_many | many_to_one | many_to_many + strength: required # optional qualitative or numeric weight + same_layer: false +attributes: + core: + criticality: high + environments: [dev, staging, prod] +provenance: + assertion_type: declared + sources: + - ref: fabric/dependencies/state-hub-runtime-secrets.yaml + method: declaration_load + observed_at: "2026-06-24T00:00:00Z" + confidence: 1.0 + freshness_state: current +``` + +### 5.1 Required edge fields + +| Field | Requirement | +|-------|-------------| +| `metadata.id` | Unique edge identifier within the graph. | +| `spec.edge_kind` | Domain-defined relationship type. | +| `spec.source_id` | Existing node `metadata.id`. | +| `spec.target_id` | Existing node `metadata.id`. | +| `spec.direction` | `directed` or `undirected`. | +| `provenance` | Same minimum provenance requirements as nodes. | + +### 5.2 Edge semantics + +- **Directed edges** express dependency, production, consumption, containment, + or influence from `source_id` to `target_id`. +- **Undirected edges** express equivalence, association, or co-location when + direction would be misleading. +- `spec.same_layer: true` marks intra-layer normalization or peer links that + should be visually and analytically distinct from cross-layer dependencies. +- `spec.strength` may be categorical (`required`, `optional`, `weak`) or + numeric. Bindings must document their scale. + +### 5.3 Multi-edges + +Multiple edges may connect the same node pair when they differ in `edge_kind`, +binding origin, or distinguishing attributes. Re-ingestion should update the +same logical edge in place when `metadata.stable_key` or a binding-supplied +dedupe key matches. + +--- + +## 6. Attributes + +Attributes carry descriptive, analytical, and presentational facts on nodes and +edges. They are grouped by namespace to keep the neutral core separable from +binding-specific and display-specific data. + +### 6.1 Namespaces + +| Namespace | Purpose | Examples | +|-----------|---------|----------| +| `core` | Stable descriptive fields useful across lenses | `description`, `owner`, `version` | +| `display` | Presentation hints for explorers | `label`, `color`, `visual_weight`, `display_state` | +| `analytical` | Metrics and derived indicators | `fan_in`, `cycle_member`, `cluster_id` | +| `binding` | Binding-private structured payload | Fabric deployment overlays, scanner hashes | +| `temporal` | Time-oriented fields | `valid_from`, `valid_to`, `observed_at` | + +Namespaces are conventional in v0.1. Implementations may store them as nested +objects (`attributes.core.description`) or flattened keys with a prefix +(`core.description`). + +### 6.2 Attribute records + +Each attribute SHOULD be representable as: + +```yaml +name: description +namespace: core +value: Runtime secrets service +value_type: string # string | number | boolean | enum | object | array | timestamp +cardinality: single # single | multi +mutable: true # whether re-ingestion may change this field in place +source: declared # declared | observed | derived | inferred +``` + +### 6.3 Typing and validation + +v0.1 does not mandate a global attribute schema. Bindings SHOULD publish: + +- allowed attributes per node/edge kind +- value types and enumerations +- required vs optional attributes +- deprecation notes for renamed attributes + +Inspection operations must treat unknown attributes as opaque but returnable. + +### 6.4 Display state + +When a graph is prepared for interactive exploration, elements may carry a +display attribute: + +| Value | Meaning | +|-------|---------| +| `show` | Fully visible with normal styling and labels. | +| `blur` | Visible but de-emphasized; details on hover or selection. | +| `hide` | Excluded from the active view but retained in the source graph. | + +Display state is a vantage-point concern. It does not change graph truth data. + +--- + +## 7. Provenance + +Provenance makes graph facts auditable. Every node and edge MUST include a +provenance block sufficient to answer: + +1. How was this fact introduced? +2. From what source material or observation? +3. How much should an operator trust it right now? + +### 7.1 Assertion types + +| Type | Meaning | +|------|---------| +| `declared` | Authored by a repo-local declaration or human assertion. | +| `observed` | Captured from runtime, repository scan, or external system query. | +| `derived` | Computed from other graph elements or transformations. | +| `inferred` | Produced by heuristic or ML extraction with weaker guarantees. | + +### 7.2 Source records + +Each `provenance.sources[]` entry SHOULD include: + +| Field | Requirement | +|-------|-------------| +| `ref` | Pointer to source artifact (path, URL, export id, scan id). | +| `method` | Binding-specific ingestion or transformation step. | +| `observed_at` | ISO-8601 timestamp for when the source was read or captured. | + +Optional source fields: + +- `actor` — human, service, or agent that triggered ingestion +- `version` — source artifact version or commit +- `checksum` — content hash for reproducibility +- `notes` — free-text operator context + +### 7.3 Confidence and freshness + +- `confidence` is a float in `[0, 1]`. Bindings should define default confidence + by assertion type when not explicitly set. +- `freshness_state` is one of `current`, `stale`, or `unknown`. +- `freshness_evaluated_at` MAY record when freshness was last assessed. + +Derived and inferred facts SHOULD reference upstream source ids or derivation +recipes under `provenance.derived_from[]`: + +```yaml +provenance: + assertion_type: derived + derived_from: + - node_id: repo:railiance-fabric + - edge_id: railiance-fabric.state-hub.requires.runtime-secrets + derivation: + method: impact_closure + recipe_version: "1" +``` + +### 7.4 Lineage inspection + +Provenance must be sufficient for the `explain` inspection operation (see +section 8.6) to reconstruct a human-readable chain from source artifacts to the +displayed fact. + +--- + +## 8. Inspection operations + +Inspection operations are read-only primitives over an NBGM graph. They are the +stable API surface between graph stores, agents, and vantage-point UIs. + +Implementations MAY expose additional operations but SHOULD support the v0.1 +baseline set or declare partial support explicitly. + +### 8.1 Operation envelope + +Operation requests and responses use a common envelope: + +```yaml +apiVersion: vantage.nbgm/v0.1 +kind: InspectionRequest +metadata: + operation: neighborhood + graph_id: example.ecosystem +spec: + parameters: {} +``` + +```yaml +apiVersion: vantage.nbgm/v0.1 +kind: InspectionResponse +metadata: + operation: neighborhood + graph_id: example.ecosystem +spec: + complete: true + result: {} + warnings: [] +``` + +### 8.2 `lookup` + +**Purpose:** Fetch one node or edge by id or stable key. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `element_type` | yes | `node` or `edge` | +| `id` | one of | Primary identifier | +| `stable_key` | one of | Durable identifier | + +**Result:** The matching element or `not_found`. + +### 8.3 `neighborhood` + +**Purpose:** Expand around a focus node to a controlled depth. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `focus_id` | yes | Starting node id | +| `depth` | yes | Hop count (1–N) | +| `edge_kinds` | no | Relationship filter | +| `direction` | no | `out`, `in`, or `both` (default `both`) | +| `max_nodes` | no | Safety cap | + +**Result:** Subgraph of nodes and edges reachable under the parameters. + +### 8.4 `path` + +**Purpose:** Find connecting paths between nodes for dependency or impact +analysis. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `source_id` | yes | Start node | +| `target_id` | yes | End node | +| `edge_kinds` | no | Allowed relationship types | +| `max_depth` | no | Search bound | +| `strategy` | no | `shortest`, `all_bounded`, or `weighted` | + +**Result:** Zero or more paths, each an ordered list of node and edge ids. + +### 8.5 `filter` + +**Purpose:** Select a subgraph by declarative predicates. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `predicate` | yes | Structured filter over kinds, labels, attributes, lifecycle, freshness | +| `include_isolated` | no | Keep nodes with no matching edges (default false) | + +**Result:** Induced subgraph containing matching elements and connecting edges +when requested. + +### 8.6 `explain` + +**Purpose:** Produce a human- and agent-readable justification for an element. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `element_type` | yes | `node` or `edge` | +| `id` | yes | Element identifier | +| `include_derivation` | no | Expand derived-from chain (default true) | + +**Result:** + +- element summary +- provenance sources and timestamps +- confidence and freshness assessment +- optional upstream path for derived/inferred facts + +### 8.7 `summarize` + +**Purpose:** Aggregate statistics for a subgraph or whole graph. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `scope` | no | Whole graph or subgraph selector | +| `metrics` | no | Requested aggregates | + +**Default metrics:** + +- counts by `node_kind` and `edge_kind` +- unresolved or stale fact counts +- top hubs by in-degree and out-degree +- connected component count + +### 8.8 `compare` + +**Purpose:** Diff two graph snapshots that share identity rules. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `baseline_graph` | yes | Reference graph id or snapshot | +| `candidate_graph` | yes | Graph to compare | +| `match_key` | no | `id` or `stable_key` (default `stable_key`) | + +**Result:** + +- `added`, `removed`, and `changed` nodes and edges +- attribute-level deltas for changed elements +- provenance changes when sources or confidence differ + +### 8.9 `violations` + +**Purpose:** Evaluate structural expectations declared by a binding or lens. + +| Parameter | Required | Description | +|-----------|----------|-------------| +| `rule_set` | yes | Binding-published constraint set | +| `severity_at_least` | no | Minimum severity to return | + +**Result:** List of violations with element refs, rule id, severity, and +recommended inspection follow-up. + +### 8.10 Operation composition + +Vantage points compose inspection operations rather than mutating the graph: + +```text +filter(layer=service) + -> neighborhood(focus=selected, depth=2, edge_kinds=[requires]) + -> summarize(metrics=[hub_rank]) + -> explain(id=top_hub) +``` + +Bindings and lenses may publish recommended operation chains for common tasks. + +--- + +## 9. Binding alignment + +NBGM is intentionally abstract. Existing repo-native graph models should +project into it without losing source-of-truth boundaries. + +### 9.1 Railiance Fabric mapping + +| Fabric concept | NBGM element | Notes | +|----------------|--------------|-------| +| Declaration `metadata.id` | `Node.metadata.id` | Preserve dotted ids. | +| Declaration kind | `Node.spec.node_kind` | `Service`, `Capability`, etc. | +| Dependency requirement | `Edge.spec.edge_kind = requires` | Directed to provider capability or interface node. | +| Binding assertion | `Edge.spec.edge_kind = binds` | Resolves consumer requirement. | +| `metadata.source_links` | `provenance.sources[].ref` | Multiple links become multiple source records. | +| Graph export payload | NBGM graph envelope + elements | Explorer display fields map to `attributes.display`. | + +Fabric remains authoritative for declarations. Vantage Point consumes exports as +an inspection-ready NBGM binding. + +### 9.2 Repo-scoping mapping + +| Repo-scoping layer | NBGM usage | +|--------------------|------------| +| `facts`, `evidence`, `features`, `capabilities`, `abilities`, `scope` | `Node.spec.layer` and `Node.spec.node_kind` | +| Evidence bridges | `Edge` with `edge_kind` reflecting support/challenge/link semantics | +| Display states in profiles | `attributes.display.display_state` | + +### 9.3 Source-of-truth rule + +Authoritative data lives in repo-native declarations, scans, or curated stores. +NBGM graphs are inspection-ready projections. Re-ingestion refreshes +projections; it does not rewrite authoritative sources. + +--- + +## 10. Examples + +### 10.1 Minimal service dependency graph + +```yaml +apiVersion: vantage.nbgm/v0.1 +kind: Graph +metadata: + id: demo.minimal + title: Minimal dependency demo + updated_at: "2026-06-24T00:00:00Z" +spec: + default_direction: directed +elements: + - kind: Node + metadata: + id: consumer.app + name: Consumer App + spec: + node_kind: Service + provenance: + assertion_type: declared + sources: + - ref: fabric/services/consumer.yaml + method: declaration_load + observed_at: "2026-06-24T00:00:00Z" + - kind: Node + metadata: + id: provider.db + name: Database + spec: + node_kind: Service + provenance: + assertion_type: declared + sources: + - ref: fabric/services/database.yaml + method: declaration_load + observed_at: "2026-06-24T00:00:00Z" + - kind: Edge + metadata: + id: consumer.app.requires.provider.db + spec: + edge_kind: requires + source_id: consumer.app + target_id: provider.db + direction: directed + provenance: + assertion_type: declared + sources: + - ref: fabric/dependencies/consumer-db.yaml + method: declaration_load + observed_at: "2026-06-24T00:00:00Z" +``` + +### 10.2 Neighborhood inspection + +```yaml +apiVersion: vantage.nbgm/v0.1 +kind: InspectionRequest +metadata: + operation: neighborhood + graph_id: demo.minimal +spec: + parameters: + focus_id: consumer.app + depth: 2 + direction: out + edge_kinds: [requires] +``` + +--- + +## 11. Open questions for v0.2 + +- Canonical serialization format (single JSON schema vs multi-document YAML) +- Global registries for cross-domain `node_kind` and `edge_kind` aliases +- Lens and vantage-point configuration schema +- Standard binding interface for incremental graph refresh +- Normative confidence and freshness scoring recipes per assertion type + +--- + +## 12. References + +- `INTENT.md` — project purpose and guiding principles +- `SCOPE.md` — repository boundary +- Meyer, Sedlmair, Munzner — *The Four-Level Nested Model Revisited: Blocks and Guidelines* ([PDF](https://miriah.github.io/publications/nbgm-beliv.pdf)) +- Railiance Fabric — `docs/declaration-schema.md`, `docs/graph-explorer-contract.md` +- Repo-scoping — dependency visualization layer model (`RREG-WP-0010`) \ No newline at end of file diff --git a/registry/capabilities/capability.graph.nbgm-spec.md b/registry/capabilities/capability.graph.nbgm-spec.md new file mode 100644 index 0000000..e8dce23 --- /dev/null +++ b/registry/capabilities/capability.graph.nbgm-spec.md @@ -0,0 +1,117 @@ +--- +id: capability.graph.nbgm-spec +name: Network-Based Graph Model (NBGM) Specification +summary: Generic system and versioned protocol specification for exploring dependency structures as network-based + graph models (NBGM), unifying entity/relationship inspection and reasoning across arbitrary domains. +owner: vantage-point +status: draft +domain: infotech +tags: +- graph +- nbgm +- specification +maturity: + discovery: + current: D2 + target: D4 + confidence: medium + rationale: SCOPE.md documents the core idea clearly (unifying entity/relationship inspection across + domains); note README.md is a stale repo-seed template leftover — SCOPE.md is authoritative. A substantial + draft protocol spec (nbgm-spec-v0.1.md, per docs/) exists. + availability: + current: A0 + target: A2 + confidence: medium + rationale: Specification-stage only; no implementation code found in this sweep (docs/ and registry/ + and workplans/ only, no src/ or package manifest). +external_evidence: + completeness: + level: C1 + confidence: low + basis: scope_vs_intent_and_consumer_expectations + satisfied_expectations: + - a versioned protocol spec (docs/nbgm-spec-v0.1.md) exists + broken_expectations: [] + out_of_scope_expectations: [] + reliability: + level: R0 + confidence: low + basis: consumer_quality_signals + known_reliability_risks: + - no implementation yet; availability is honestly A0 pending an actual reference implementation +discovery: + intent: Define a generic, versioned protocol for exploring dependency structures as network-based graph + models, applicable across arbitrary domains, not tied to one specific graph engine. + includes: + - NBGM protocol specification (versioned) + - entity/relationship inspection and reasoning model + excludes: + - a reference implementation (not yet built) + assumptions: [] + use_cases: [] + research_memos: [] +availability: + current_level: A0 + target_level: A2 + current_artifacts: + - docs/nbgm-spec-v0.1.md + target_artifacts: [] + consumption_modes: + - informational (specification only) +relations: + depends_on: [] + supports: [] + related_to: [] +evidence: + documentation: + - SCOPE.md + - docs/nbgm-spec-v0.1.md + tests: [] + consumer_feedback: [] + bug_reports: [] + incidents: [] +consumer_guidance: + recommended_for: + - repos designing a graph-based dependency/entity model wanting to align with a shared, versioned protocol + before building their own + not_recommended_for: + - needs for a working graph implementation today (specification only, no code yet) + known_limitations: + - specification-stage only; no reference implementation exists yet +promotion_history: [] +--- + +# Network-Based Graph Model (NBGM) Specification + +## Overview + +`vantage-point` defines the Network-Based Graph Model (NBGM): a generic, versioned protocol for exploring dependency structures as graph models, unifying entity/relationship inspection and reasoning across arbitrary domains. It is specification-stage only — a real, versioned spec document exists, but no reference implementation has been built yet. + +## Assessment notes + +### Discovery + +SCOPE.md documents the core idea clearly (unifying entity/relationship inspection across domains); note README.md is a stale repo-seed template leftover — SCOPE.md is authoritative. A substantial draft protocol spec (nbgm-spec-v0.1.md, per docs/) exists. + +### Availability + +Specification-stage only; no implementation code found in this sweep (docs/ and registry/ and workplans/ only, no src/ or package manifest). + +### Completeness + +First-pass honest assessment from the REUSE-WP-0017 coverage campaign +(reuse-surface). No external consumer feedback exists yet; levels reflect +scope-vs-intent documentation quality, not internal code quality. + +### Reliability + +No production consumer telemetry exists yet; reliability level is +intentionally conservative pending REUSE-WP-0019 reuse-telemetry evidence. + +## Promotion checklist + +- [x] ID follows `capability..` pattern +- [x] Maturity enums match `specs/CapabilityMaturityStandard.md` +- [x] `external_evidence` is populated separately from `maturity` +- [ ] Relations reference valid capability IDs (none yet) +- [x] Index entry added in `registry/indexes/capabilities.yaml` diff --git a/registry/indexes/capabilities.yaml b/registry/indexes/capabilities.yaml index f944e47..dda81c4 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,4 +1,20 @@ version: 1 -updated: '2026-06-16' +updated: '2026-07-06' domain: helix_forge -capabilities: [] +capabilities: +- id: capability.graph.nbgm-spec + name: Network-Based Graph Model (NBGM) Specification + summary: Generic system and versioned protocol specification for exploring dependency structures as + network-based graph models (NBGM), unifying entity/relationship inspection and reasoning across arbitrary + domains. + vector: D2 / A0 / C1 / R0 + domain: infotech + status: draft + owner: vantage-point + path: registry/capabilities/capability.graph.nbgm-spec.md + tags: + - graph + - nbgm + - specification + consumption_modes: + - informational (specification only) diff --git a/workplans/VANTAGE-WP-0001-statehub-bootstrap.md b/workplans/VANTAGE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..1fff87a --- /dev/null +++ b/workplans/VANTAGE-WP-0001-statehub-bootstrap.md @@ -0,0 +1,67 @@ +--- +id: VANTAGE-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: infotech +repo: vantage-point +status: finished +owner: codex +topic_slug: infotech +created: "2026-06-22" +updated: "2026-06-22" +state_hub_workstream_id: "9f12270d-44f9-4217-a672-bb5fc2bf7c0f" +--- + +# Bootstrap State Hub integration + +Vantage point observability tooling. + +## Review Generated Integration Files + +```task +id: VANTAGE-WP-0001-T01 +status: done +priority: high +state_hub_task_id: "a99f9783-0490-4a13-b875-ad0851662aad" + +``` + +Result 2026-06-22: Filled SCOPE.md from INTENT. + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +## Verify Local Developer Workflow + +```task +id: VANTAGE-WP-0001-T02 +status: done +priority: high +state_hub_task_id: "b2b0f201-2eb9-4197-8de7-56f404bf623f" + +``` + +Result 2026-06-22: Registry workflow 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. + +## Seed First Real Workplan + +```task +id: VANTAGE-WP-0001-T03 +status: done +priority: medium +state_hub_task_id: "4bce0d0d-d4ad-4c5a-ae12-75ec8a40455b" + +``` + +Result 2026-06-22: Created VANTAGE-WP-0002. + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run from `~/state-hub`: + +```bash +make fix-consistency REPO=vantage-point +``` diff --git a/workplans/VANTAGE-WP-0002-nbgm-spec-baseline.md b/workplans/VANTAGE-WP-0002-nbgm-spec-baseline.md new file mode 100644 index 0000000..1f6af1e --- /dev/null +++ b/workplans/VANTAGE-WP-0002-nbgm-spec-baseline.md @@ -0,0 +1,30 @@ +--- +id: VANTAGE-WP-0002 +type: workplan +title: "NBGM model specification baseline" +domain: infotech +repo: vantage-point +status: finished +owner: codex +topic_slug: infotech +created: "2026-06-22" +updated: "2026-06-24" +state_hub_workstream_id: "bd2d70eb-4c83-4fa3-94ff-7f44b32aeba9" +--- + +# NBGM model specification baseline + +Author the network-based graph model specification baseline. + +## NBGM spec v0.1 + +```task +id: VANTAGE-WP-0002-T01 +status: done +priority: high +state_hub_task_id: "d13bd898-15b0-41ba-aa3b-8c5f96a09fd8" +``` + +Result 2026-06-24: Authored `docs/nbgm-spec-v0.1.md` covering graph envelope, +nodes, edges, attribute namespaces, provenance/lineage, inspection operations, +and binding alignment for Railiance Fabric and repo-scoping.