{
  "id": "page:process-00-process-design",
  "_kind": "Page",
  "_file": "wiki/process/00-process-design.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "v6 Ontology-Driven Development Process — Master Design",
    "displayName": "v6 Ontology-Driven Development Process — Master Design",
    "slug": "process/00-process-design",
    "articlePath": "wiki/process/00-process-design.md",
    "article": "# v6 Ontology-Driven Development Process — Master Design\n\n> Definitive specification for how the v6 effort runs end-to-end. The schema and graph live under `C:/work/v6/graph/`; this document describes the process that produces, evolves, and delivers everything derived from them.\n\n---\n\n## 1. Vision\n\nThe **agent-catalog graph** is the single source of truth for the v6 domain. Every other artifact — node-kind specs, validation rules, generated documentation, the wiki, generator code, the SDK, and user-facing interfaces — is a *projection* of the graph, never authored independently.\n\nThe flow is strict and one-directional:\n\n```\nSchema (C:/work/v6/graph/schema/ontology-schema.yaml)\n   ↓\nGraph (populated nodes + edges + evidence)\n   ↓\nDerived artifacts (docs, generators, tests, code, SDK, interfaces)\n```\n\nBecause prose is regenerated from the graph, **prose drift is structurally impossible**: if a fact changes, the change is made in the graph, and every projection that depends on that fact is regenerated. Out-of-band edits to derived artifacts are rejected by CI.\n\nThe graph aspires to **wiki-grade thoroughness**: it must hold enough structured fact and evidence (per `C:/work/v6/graph/schema/evidence-model.md`) to write a full encyclopedia of the agent / Claude Code / babysitter ecosystem — every Term defined, every Product specified, every Capability sourced, every Hook documented, every Channel typed. If a human reader needs to know it, the graph must hold it as data + evidence, not as floating prose.\n\n---\n\n## 2. Phases 1–5\n\nThe forward direction is **top-down**: each phase initially completes before the next begins. Each phase has explicit deliverables and acceptance criteria. Phases are revisited continuously through the debt-driven loop (Section 3).\n\n### Phase 1 — Schema (mostly done)\n\n**Deliverables**\n- Meta-schema: `C:/work/v6/graph/schema/meta-schema.md`\n- 14 node-kind specs under `C:/work/v6/graph/schema/node-kinds/` (agent-stack, benchmarks, capabilities, catalog-meta, channels-hooks, domain-ontology, extensions-plugins, lifecycle, role-ontology, sourceref-and-scope, stack-layers, terminology, transport, trust). Note: the `trust` spec is slimmed to `TrustLevel` only — the cross-stack Trust Chain (`Authority`, `Attestation`, `trust-interface`) is out-of-scope for Phase 1 and deferred to a separate trust-and-signing initiative if pursued.\n- Edge-kind spec: `C:/work/v6/graph/schema/edge-kinds.md`\n- Machine-readable schema files: `C:/work/v6/graph/schema/ontology-schema.yaml`, `attribute-types.yaml`, `invariants.yaml`\n- Evidence model: `C:/work/v6/graph/schema/evidence-model.md`\n- Validation rules: `C:/work/v6/graph/schema/validation-rules.md`\n- Derivation spec: `C:/work/v6/graph/schema/derivation-spec.md`\n- Versioning: `C:/work/v6/graph/schema/versioning.md`\n- Coverage checklist: `C:/work/v6/graph/coverage-checklist.md`\n\n**Acceptance criteria**\n- Every legacy concept (from `C:/work/v6/graph/wiki/legacy/`) maps to a schema element or is explicitly marked out-of-scope.\n- All 29 OpenQuestions raised during schema authoring are resolved or formally deferred (deferred questions tracked as `Gap` nodes per Section 6).\n- A validator stub exists that loads `ontology-schema.yaml` + `invariants.yaml` and reports structural violations on a sample graph.\n\n### Phase 2 — Full graph\n\n**Deliverables**\n- Complete graph population covering every named real-world entity in scope. Current state: the graph data under `C:/work/v6/graph/` is still sample-heavy and needs full coverage.\n- Every node carries live evidence pointing into `SourceRef` nodes (per `schema/evidence-model.md`).\n\n**Acceptance criteria**\n- Every NodeKind has full real-world coverage where applicable (concrete entities, not just samples).\n- Every fact-bearing claim has live evidence within the freshness window defined in `04-evidence-model.md`.\n- Cross-reference integrity is 100%: no dangling edge endpoints, no orphan nodes outside the explicitly-orphan-allowed kinds.\n- The validator stub from Phase 1 passes on the full graph, with zero invariant violations.\n\n### Phase 3 — Generators\n\n**Deliverables**\n- Generator implementations for the 10 illustrative outputs in `C:/work/v6/graph/schema/derivation-spec.md`:\n  1. Glossary\n  2. Stack documentation\n  3. Product card\n  4. Capability matrix\n  5. Hook taxonomy doc\n  6. Adapter scaffold\n  7. OpenAPI artifact\n  8. Per-package README\n  9. Stack diagram\n  10. Coverage check\n\n**Acceptance criteria**\n- Generators are **pure**, **deterministic**, **idempotent**: same graph in → byte-identical output.\n- Output diffs only when the graph (or generator code) changes; running a generator twice in a row produces no diff.\n- Each generator emits a manifest declaring which graph nodes/edges it read.\n\n### Phase 4 — Documentation / wiki\n\n**Deliverables**\n- A full wiki/encyclopedia derived from the graph: per-NodeKind page, per-Product page, per-Capability page, per-Term entry, per-Hook entry, per-Channel entry, per-Stack-layer page.\n- Phase-by-phase architecture pages.\n- Navigation, full-text search, cross-references between every named graph entity.\n- Glossary auto-generated from `Term` nodes.\n\n**Acceptance criteria**\n- Every `Term` in the graph has a wiki page.\n- Every `Product` has a page.\n- Every `Capability` has a page.\n- Navigation works (no dead links from generated nav).\n- Search returns expected hits for spot-check queries pulled from the graph.\n\n### Phase 5 — Testing / verification / delivery\n\n**Deliverables**\n- Test pyramid: unit tests per generator, integration tests across schema → graph → generator, end-to-end tests on shipped artifacts.\n- Evidence-boundary checks (claims without evidence fail; stale evidence fails).\n- Schema-version delivery and generator versioning per `C:/work/v6/graph/schema/versioning.md`.\n- CI/CD pipeline that gates schema and graph PRs.\n- Downstream artifact distribution (npm packages, generated docs site, OpenAPI artifacts, etc.).\n\n**Acceptance criteria**\n- Every NodeKind has at least one test.\n- Every generator has an integration test against a known graph fixture.\n- E2E tests exist for key user flows (e.g., schema change → regenerated docs → SDK consumer compiles).\n- CI gates schema/graph PRs on validator + invariant + freshness checks.\n\n---\n\n## 3. Debt-driven loop\n\nThe debt loop runs **between each forward phase** and **continuously after all phases complete**. It identifies and closes drift between the seven levels listed below. Each iteration: pick the highest-priority unaddressed gap, close it, then cascade per Section 4.\n\n### The 7 levels (priority order — lower number wins)\n\n1. **Real world vs graph + schema** — vendor news, third-party updates, online sources, analytics, bug reports, feature requests. New Anthropic capabilities, new Claude Code releases, breaking SDK changes, new MCP servers, new community plugins, deprecations, pricing/quota changes.\n2. **Graph vs docs** — graph data and node-kind/edge-kind specs in agreement; example YAMLs valid against the schema; invariants in `invariants.yaml` reflected in `schema/validation-rules.md` prose.\n3. **Quality / delivery process vs docs** — the Phase 5 artifacts (CI, versioning, distribution) match what the docs say they should produce.\n4. **Generators vs docs** — Phase 3 generators emit exactly what `schema/derivation-spec.md` says they should emit, with no extra fields and no missing fields.\n5. **Code vs docs + above** — implementation code (validators, generators, runtime libraries) matches the schema and the spec; no hardcoded facts that should be derived.\n6. **Programmable interfaces vs SDK + above** — the SDK surface (TypeScript types, function signatures, exported constants) matches the schema-derived contract.\n7. **Interfaces vs everything above** — user-facing interfaces (CLI, web UI, dashboards) match the SDK surface and the spec.\n\n### Why priority order matters\n\nA gap at Level 1 invalidates derivations at Levels 2–7. Fixing a Level 5 issue while a Level 1 gap is open is wasted work — the truth changed underneath you. Always resolve Level N before spending energy on Level N+1, **unless** Level N+1 work is the cascade of a Level N fix already in progress (Section 4).\n\n### Sources of Level-1 signal\n\n- Anthropic changelog, model release notes, system card updates\n- Claude Code release notes, plugin marketplace updates\n- MCP registry updates\n- GitHub issues and PRs in tracked upstreams\n- User feedback (bug reports, feature requests)\n- Telemetry / analytics on shipped artifacts (which generators were rerun, which docs were viewed, which SDK calls 404'd)\n\n### What \"closing a gap\" means\n\nA gap is closed when:\n- The change is committed to the graph (and schema, if needed).\n- All cascaded changes (Section 4) are committed or explicitly marked `not-applicable`.\n- Adversarial review (Section 5) signs off.\n- The gap node's `status` flips from `open` → `closed` and `propagationStatus` is `done`/`not-applicable` for every level.\n\n---\n\n## 4. Cascade rule\n\nWhen closing a gap at Level N, **propagate the change DOWN through Levels N+1...7 BEFORE picking up generic gaps at higher levels**.\n\nConcretely, a Level 1 gap (e.g., \"Anthropic shipped a new caching primitive\") triggers:\n\n- **Level 1**: graph data updated; schema extended if a new attribute or NodeKind is needed.\n- **Level 2**: node-kind specs under `schema/node-kinds/` updated; example YAMLs added; `coverage-checklist.md` updated.\n- **Level 3**: any process docs that referenced the now-stale state are updated (this document, release notes, runbooks).\n- **Level 4**: regenerate affected wiki pages (new Capability page, updated Product page, updated glossary entries).\n- **Level 5**: any code paths that depend on the changed claim (validators, generators, runtime helpers) updated.\n- **Level 6**: SDK signatures regenerated; type tests updated.\n- **Level 7**: user-facing interfaces (CLI flags, dashboard widgets) updated.\n\nTrack propagation explicitly in the gap entry's `propagationStatus` field (Section 6). A gap is **not** closed until every applicable level is `done`. Levels that genuinely don't apply must be set to `not-applicable` with a one-line reason.\n\nThe cascade rule prevents the most common failure mode of the debt loop: closing a high-priority gap at its origin level and leaving downstream projections inconsistent.\n\n---\n\n## 5. Adversarial review\n\nEvery gap closure goes through an **independent adversarial reviewer** before it's marked closed. The reviewer reads the proposed change against this spec and the schema, looking specifically for:\n\n- Missing cascade steps (Level N fixed, Level N+k forgotten).\n- Evidence that doesn't support the claim, or evidence outside the freshness window.\n- Schema changes without corresponding `versioning.md` bumps.\n- Generator output drift not reflected in tests.\n- Hidden coupling — a \"small\" change at one level that silently shifts behavior at another.\n\nThe reviewer **must be a different identity** from the implementer: a different agent invocation, a different human, or both. Same-identity review is structurally blind to the implementer's assumptions and is rejected. The reviewer's findings either gate the close (must-fix) or attach as follow-up gap nodes (next-cycle).\n\n---\n\n## 6. Tracking\n\nGaps are **first-class graph entities**. We extend `ontology-schema.yaml` with a new `NodeKind: Gap` so the debt loop is itself part of the graph and visible to every generator.\n\n### `Gap` node attributes\n\n| Attribute | Type | Notes |\n|---|---|---|\n| `id` | string | `GAP-<level>-<priority>-<slug>` |\n| `title` | string | One-line human title |\n| `level` | int (1–7) | Per Section 3 |\n| `priority` | enum | `P0` \\| `P1` \\| `P2` \\| `P3` |\n| `discoveredAt` | timestamp | When first noted |\n| `source` | string | URL, channel, or person |\n| `currentState` | text | What the system says today |\n| `desiredState` | text | What it should say |\n| `propagationStatus` | object | Per-level: `not-started` \\| `in-progress` \\| `done` \\| `not-applicable` (with reason) |\n| `owner` | ref → Authority | Per Section 8 |\n| `evidenceLinks` | list → SourceRef | Per `04-evidence-model.md` |\n| `status` | enum | `open` \\| `in-progress` \\| `closed` \\| `deferred` |\n| `notes` | text | Free-form |\n| `propagationChain` | list of `{level, fix, by, at}` | Audit trail |\n\nEach tracked gap also has a markdown file at `C:/work/v6/graph/wiki/process/gaps/GAP-<level>-<priority>-<slug>.md` (the human-readable form). The YAML form lives in `C:/work/v6/graph/catalog-meta/gaps/` like every other graph entity. The two are kept in sync by a generator (one of the Phase 3 deliverables, added to the `schema/derivation-spec.md` list as the eleventh output).\n\n---\n\n## 7. Iteration cadence\n\n| Level | Cadence |\n|---|---|\n| 1 — Real world vs graph | Continuous monitoring; weekly batch review |\n| 2 — Graph vs docs | Every PR (CI gate) |\n| 3 — Process docs | Monthly |\n| 4 — Generators / wiki | Every PR (regenerate-on-merge) + weekly full regeneration |\n| 5 — Code vs docs | Every PR + every release |\n| 6 — SDK | Every release |\n| 7 — Interfaces | Every release |\n\nP0 gaps at any level interrupt cadence and are addressed immediately.\n\n---\n\n## 8. Governance\n\n| Role | Scope |\n|---|---|\n| **Schema owner** | Phase 1 deliverables; final say on `ontology-schema.yaml` shape |\n| **Graph data owners** | Phase 2; one per node-kind cluster (e.g., one for `capabilities` + `channels-hooks`, one for `agent-stack` + `extensions-plugins`, etc.) |\n| **Generator owners** | Phase 3; one per generator listed in `schema/derivation-spec.md` |\n| **Wiki editors** | Phase 4; navigation, search, page templates (content itself is generated) |\n| **QA owner** | Phase 5; CI, versioning, distribution, evidence-boundary enforcement |\n| **Debt-loop coordinator** | Cross-cutting; ensures the cascade rule (Section 4) is applied on every gap closure; runs the weekly Level-1 batch review |\n\nAll owners are represented as `Authority` nodes in the graph and referenced from the `owner` field of `Gap` nodes.\n\n---\n\n## 9. Acceptance gates\n\nA phase is complete when **all** of the following hold:\n\n1. Its deliverables (Section 2) exist and are in the repo.\n2. Tests pass — unit, integration, and any e2e tests that apply at that phase.\n3. Adversarial review (Section 5) signs off on the phase's deliverables as a whole.\n4. A debt-loop pass at the current phase's level finds **no P0 or P1 gaps**. P2/P3 gaps may remain open with explicit deferral.\n\nGates are evaluated at PR merge time (per-deliverable) and at phase-close time (overall).\n\n---\n\n## 10. Deliverables enumeration\n\n- **Schema**: meta-schema + 14 node-kind specs + `ontology-schema.yaml` + `attribute-types.yaml` + `invariants.yaml` + evidence model + validation rules + derivation spec + versioning + coverage checklist + `Gap` NodeKind tracking.\n- **Graph**: full population per NodeKind, with evidence, under `C:/work/v6/graph/`.\n- **Generators**: 10+ per `schema/derivation-spec.md`, plus the `Gap` markdown<->YAML sync generator.\n- **Wiki**: full encyclopedia + navigation + search; one page per Term, Product, Capability, Hook, Channel, Stack layer.\n- **QA**: tests + e2e + evidence-boundary checks + coverage report + versioning policy + CI/CD + downstream artifact distribution.\n- **Code**: validators, generators, and runtime helpers — all derived from / driven by the schema.\n- **SDK**: programmable interfaces (TypeScript types, runtime helpers) generated from the schema contract.\n- **Interfaces**: user-facing surfaces (CLI, dashboard, docs site) consuming the SDK.\n\n---\n\n## 11. Open questions about the process itself\n\n- Should `Gap` nodes participate in the same evidence-freshness rules as factual nodes, or do they get their own freshness policy (e.g., open >90 days = auto-escalate priority)?\n- Where does the Level-1 monitoring tooling itself live — inside this repo, or as a separate side-car? (Affects how the weekly batch review is automated.)\n- Who arbitrates when two graph data owners disagree on a cross-cluster edge? Default: schema owner; needs confirmation.\n- Is \"adversarial review by a different agent invocation\" sufficient, or must at least one human reviewer be in the loop for schema changes? Lean: human-required for schema, agent-sufficient for graph data.\n- Cascade rule defines top-down propagation. Do we ever need bottom-up propagation (e.g., interface constraint forcing a schema change)? If so, that's a Level-1 gap with the interface as `source` — confirm this framing is sufficient.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": []
}