Skip to content
TapPass Internal

ADR 0004 — Capability tree

ADR 0004 — Capability tree

Section titled “ADR 0004 — Capability tree”

Date: 2026-05-08 Status: Accepted Strategic frame: Product vision — TapPass as central governance layer, headless-first

Context

Section titled “Context”

The platform now spans many buildable blocks: policy authoring, compilation, evaluation, runtime translation, multiple operator surfaces (UI / CLI / agentic CLI / MCP), a tool catalog with audit-driven discovery, agent templates, multi-tenant org structure, audit + session observability, sandbox runtime, LLM provider integrations, plus the TapPass Chat first-party product.

Existing artifacts cover slices:

  • architecture/concepts/ — 24 concept cards, one per domain entity
  • architecture/strategic/ — long-form Q-numbered design questions (q03–q15)
  • build/components/ — implementation-level component cards across three views (by question, by engine, by data object)
  • build/roadmap-2026-h2.md — time-bound delivery plan

What's missing is a single living map that answers "what is TapPass made of, and when does each block land?" — without dates, without a flat list, without duplicating the concept cards.

Decision

Section titled “Decision”

Create one Markdown file at src/content/docs/capability-tree.md (top-level — its own sidebar section after Set the scene, not buried under Architecture or Build) that:

  1. Spine — six top-level capabilities (outcome-shaped, not component-shaped):

    • Govern — policy authoring, compilation, evaluation, translation
    • Configure — operator surfaces (UI, CLI, MCP, SDK, onboarding)
    • Catalog — pre-built blocks operators pick from
    • Observe — visibility into running activity
    • Organise — multi-tenant structure
    • Run — runtime substrate where agents execute

  2. Leaf schema — every leaf is one Markdown block with exactly four fields:

    ### Leaf Name
    One-sentence purpose statement.
    **Horizon:** Now · **Depends on:** Other Leaf, Other Leaf · **Doc:** [doc-name](/path/to/doc/)
    • Horizon — exactly one of Now / Next / Later / Future / Retired
    • Depends on — comma-separated leaf names (linked) or —
    • Doc — Starlight-relative URL, or — if no doc exists yet

    No status, owner, rationale, or acceptance criteria. Detail belongs in the linked concept doc.

  3. Hierarchy — exactly two levels (capability → leaf). No sub-leaves.

  4. Coverage — full platform: shipped + in-flight + future, all on the same map.

  5. Cross-cutting rule — a leaf has exactly one home (its primary capability — the one whose audience would first look for it). Other capabilities reference it via Depends on:. Never duplicate a leaf across branches.

  6. Maintenance — single file; edits are PRs against it. Retired leaves don't get deleted, they get Horizon: Retired and stay in the map for historical onboarding context.

Consequences

Section titled “Consequences”
  • New artifact, no existing artifact replaced. Concept cards remain the source of truth for what each block is. The tree is the source of truth for how blocks compose into the platform and when each lands.
  • Two splits required in architecture/concepts/:
    • concepts/provider.md → split into concepts/policy-provider.md (translates compiled policy → runtime config) and concepts/llm-provider.md (LLM integrations like Anthropic, OpenAI). The current shared file conflates two different concepts.
  • Missing concept docs surfaced. Authoring the tree exposes leaves with no concept doc yet (Doc: —): MCP Server, SDK (admin), Tool Discovery, Check Pack, Pipeline Findings, Tool Footprint, Metering, Organisation, TapPass Chat. Each becomes a follow-up authoring task.
  • q05 and q08 promoted to leaves. q05-business-user-onboarding becomes the Operator Onboarding leaf in Configure; q08-pre-deployment-evaluation becomes the Pre-deploy Policy Evaluation leaf in Govern. They describe distinct buildable surfaces, not just rationale.
  • Other Q-docs stay rationale-only. q03, q06, q09, q10, q12 inform multiple leaves and remain referenceable, but do not appear as nodes.
  • TapPass Chat appears as one Run leaf — the platform tree treats it as a first-party governed-chat runtime. If TapPass Chat needs decomposition into its own building blocks (overlay layout, upstream-sync process, hardening contract, branding, license layer), it gets its own capability-tree document — not crammed into this one.

Alternatives considered

Section titled “Alternatives considered”

Spine by component/system

Section titled “Spine by component/system”

Rejected. Top branches would mirror architecture/concepts/ (Policy Engine, Policy Compiler, Pipeline, …). Closely matches existing structure but reproduces the concept-card view rather than adding a new lens. Capability/outcome spine is more useful for scoping — it groups blocks by what they let an operator do, not by what they are.

Spine by release version

Section titled “Spine by release version”

Rejected. Top branches would be v1.0, v1.1, v2.0, Future. Maximises roadmap clarity but the tree gets reshuffled every release and loses long-term reference value. Horizons-as-leaf-tag preserves the same scoping capability without destabilising the spine.

Spine by configuration surface

Section titled “Spine by configuration surface”

Rejected. Top branches would be UI / CLI / MCP / SDK. Reflects the headless-future ambition but spreads core domain logic (policy, audit, sandbox) across four branches arbitrarily.

Heavy leaves with full requirements (shall-statements, acceptance criteria, owner)

Section titled “Heavy leaves with full requirements (shall-statements, acceptance criteria, owner)”

Rejected. The tree would become a requirements register, duplicating the concept cards and growing high-maintenance. Light leaves keep it scannable; concept cards keep the depth.

Directory of files (one per capability)

Section titled “Directory of files (one per capability)”

Rejected. Six files plus an index would lose the single-screen overview and require an index that always drifts. Single Markdown file with ## per capability stays under ~250 lines with light leaves.

Migration path

Section titled “Migration path”
ActionStatus
Author src/content/docs/capability-tree.md per this design (top-level page, not under architecture/)✅ done 2026-05-08
Add Capability tree as its own top-level sidebar section in astro.config.mjs, positioned after Set the scene✅ done 2026-05-08
Split concepts/provider.md → concepts/policy-provider.md + concepts/llm-provider.md✅ done 2026-05-08
Author missing concept docs flagged with Doc: — (MCP Server, SDK admin, Tool Discovery, Check Pack, Pipeline Findings, Tool Footprint, Metering, Organisation, TapPass Chat, Agentic CLI)✅ done 2026-05-08 (initial cards landed; can be deepened over time)
Decide horizons per leaf (Now / Next / Later / Future)✅ done 2026-05-08 — distribution: 17 Now / 9 Next / 9 Later / 4 Future

References

Section titled “References”