diff --git a/.claude/rules/agents.md b/.claude/rules/agents.md deleted file mode 100644 index 0e8a5d9..0000000 --- a/.claude/rules/agents.md +++ /dev/null @@ -1,20 +0,0 @@ -## 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 deleted file mode 100644 index 7c2a645..0000000 --- a/.claude/rules/architecture.md +++ /dev/null @@ -1,8 +0,0 @@ -## 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 deleted file mode 100644 index b9c8fc5..0000000 --- a/.claude/rules/credential-routing.md +++ /dev/null @@ -1,50 +0,0 @@ -# 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 deleted file mode 100644 index 24046ad..0000000 --- a/.claude/rules/first-session.md +++ /dev/null @@ -1,38 +0,0 @@ -## 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 deleted file mode 100644 index 1270237..0000000 --- a/.claude/rules/repo-boundary.md +++ /dev/null @@ -1,8 +0,0 @@ -## 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 deleted file mode 100644 index 1bf15e8..0000000 --- a/.claude/rules/repo-identity.md +++ /dev/null @@ -1,5 +0,0 @@ -**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 deleted file mode 100644 index 8379e29..0000000 --- a/.claude/rules/session-protocol.md +++ /dev/null @@ -1,85 +0,0 @@ -## 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 deleted file mode 100644 index 6d2a123..0000000 --- a/.claude/rules/stack-and-commands.md +++ /dev/null @@ -1,20 +0,0 @@ -## 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 deleted file mode 100644 index f593791..0000000 --- a/.claude/rules/workplan-convention.md +++ /dev/null @@ -1,40 +0,0 @@ -## 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 deleted file mode 100644 index 613236e..0000000 --- a/.custodian-brief.md +++ /dev/null @@ -1,18 +0,0 @@ - -# 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 deleted file mode 100644 index bd44c56..0000000 --- a/.forgejo/workflows/ci-smoke.yaml +++ /dev/null @@ -1,29 +0,0 @@ -# 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 deleted file mode 100644 index 87784cd..0000000 --- a/.repo-classification.yaml +++ /dev/null @@ -1,21 +0,0 @@ -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 deleted file mode 100644 index 7ac0794..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,219 +0,0 @@ -# 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 deleted file mode 100644 index da62965..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,12 +0,0 @@ -# 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 0e27c33..fcd7b8f 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,3 @@ -# vantage-point +# repo-seed -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. +A git repository template to bootstrap coulomb projects from. \ No newline at end of file diff --git a/SCOPE.md b/SCOPE.md deleted file mode 100644 index e1041e6..0000000 --- a/SCOPE.md +++ /dev/null @@ -1,31 +0,0 @@ -# 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 deleted file mode 100644 index 25d553c..0000000 --- a/docs/nbgm-spec-v0.1.md +++ /dev/null @@ -1,671 +0,0 @@ -# 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 deleted file mode 100644 index e8dce23..0000000 --- a/registry/capabilities/capability.graph.nbgm-spec.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -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 dda81c4..f944e47 100644 --- a/registry/indexes/capabilities.yaml +++ b/registry/indexes/capabilities.yaml @@ -1,20 +1,4 @@ version: 1 -updated: '2026-07-06' +updated: '2026-06-16' domain: helix_forge -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) +capabilities: [] diff --git a/workplans/VANTAGE-WP-0001-statehub-bootstrap.md b/workplans/VANTAGE-WP-0001-statehub-bootstrap.md deleted file mode 100644 index 1fff87a..0000000 --- a/workplans/VANTAGE-WP-0001-statehub-bootstrap.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -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 deleted file mode 100644 index 1f6af1e..0000000 --- a/workplans/VANTAGE-WP-0002-nbgm-spec-baseline.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -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.