# ADR-001: Business Knowledge System — Connector-Fed Extraction with Dual-Location Model

**Date:** 2026-04-21
**Status:** Accepted
**Deciders:** Chad Warner, Architecture Advisor

## Context

The harness system makes technically sound decisions but lacks business domain awareness. Skills like architecture-advisor, code-review, and planning operate without understanding why code matters to the business — what domains are revenue-critical, what compliance rules apply, what SLAs are contractual, or what strategic direction is guiding decisions.

The current system has:

- A knowledge graph with 28 node types, none representing business knowledge
- External connectors (Jira, Slack, Confluence, CI) that extract data but discard business-rich signals (comments, custom fields, attachments, page hierarchy, thread decisions)
- Session sections (terminology, decisions, constraints) that are ephemeral — knowledge dies when the session ends
- No mechanism for visual knowledge ingestion (diagrams, mockups, charts)
- A 2000-character truncation on all connector content, losing most Confluence page bodies

The goal: skills automatically surface business context for the domains they touch, without being told each time.

## Decision

Implement a **connector-fed business knowledge system** with auto-extraction from code signals and external systems, a `KnowledgeLinker` post-processing pass, diagram-as-code parsing, a `/harness:knowledge-pipeline` for drift detection, and a **dual-location storage model** that separates authoritative human-curated knowledge from provisional auto-extracted knowledge.

### Storage Model

**`docs/knowledge/<domain>/`** — Human-authored, PR-reviewed, authoritative.

- Narratives (strategic context), curated facts (verified business rules), concepts (linked domain topics)
- Read by `BusinessKnowledgeIngestor` into graph nodes with `confidence: 1.0`
- Follows the same pattern as `docs/adr/` → KnowledgeIngestor → graph

**`.harness/knowledge/`** — System-managed, provisional, pipeline-maintained.

- `extracted/` — Auto-gleaned facts from connectors and code signals (JSONL with confidence scores)
- `staged/` — High-confidence extractions awaiting human promotion to `docs/knowledge/`
- `gaps.md` — Knowledge gaps detected by pipeline (domains with low coverage)

**Promotion flow:** Extraction → `.harness/knowledge/extracted/` → Pipeline validates → `.harness/knowledge/staged/` → Human promotes via PR → `docs/knowledge/` → Graph ingestion at full confidence.

### Knowledge Hierarchy (3-Tier)

| Tier          | Node Type            | Description                    | Size               | Example                                                   |
| ------------- | -------------------- | ------------------------------ | ------------------ | --------------------------------------------------------- |
| **Fact**      | `business_fact`      | Single assertion with evidence | 1 sentence         | "Settlement SLA: <2s per contract §4.2"                   |
| **Concept**   | `business_concept`   | Bounded topic linking facts    | 1 paragraph–1 page | "Payment domain: SLAs, compliance, flow, partners"        |
| **Narrative** | `business_narrative` | Strategic context, direction   | Multi-paragraph    | "Why our payment architecture is a competitive advantage" |

### Graph Schema Extensions

**New node types** (added to `packages/graph/src/types.ts`):

- `business_fact` — atomic business assertion
- `business_concept` — linked group of facts
- `business_narrative` — strategic context document
- `business_rule` — regulatory/operational constraint
- `business_process` — workflow or lifecycle

**New edge types:**

- `supports` — code implements or supports a business capability
- `constrains` — business rule constrains code behavior
- `contains` (reuse existing) — concept contains facts, narrative contains concepts

### Knowledge Sources (4 Channels)

**Channel 1: Code Signal Extractors**

- Test description extractor — `describe()/it()` blocks encode business rules in natural language
- Enum/constant extractor — domain vocabulary (`OrderStatus.FULFILLED`, `MAX_SETTLEMENT_AMOUNT`)
- Validation rule extractor — business constraints in validators
- API path extractor — domain model from route definitions

**Channel 2: Enhanced Connectors**

- Jira: extract comments, custom fields, epic context, acceptance criteria; configurable truncation
- Slack: extract thread structure, reaction patterns (consensus signals), referenced documents
- Confluence: configurable truncation (8000+), page hierarchy as knowledge taxonomy, labels
- New GitHub Issues/PRs connector for design decisions

**Channel 3: Diagram-as-Code Parser**

- Parse Mermaid, PlantUML, D2 files in the repository
- Extract entities (boxes → concepts), relationships (arrows → edges), labels (→ facts)
- Versionable in git, diff-able, reviewable

**Channel 4: Human Authoring**

- Strategic narratives that cannot be auto-extracted
- Corrections and enrichments to auto-extracted knowledge
- Authored in `docs/knowledge/`, reviewed in PRs

### KnowledgeLinker (Post-Processing)

New second-pass processor modeled on `TopologicalLinker`:

- Runs after all connectors + code ingestors complete
- Scans ingested `issue`, `conversation`, `document` nodes for business rule patterns
- Clusters related nodes into `business_concept` groups
- Promotes high-confidence extractions to `business_fact` nodes
- Cross-links related knowledge across sources
- Deduplicates: same rule from Jira AND code validator → single fact with multiple evidence citations

### Knowledge Pipeline (`/harness:knowledge-pipeline`)

Four-phase convergence loop:

1. **EXTRACT** — Run extractors across codebase + external systems
2. **RECONCILE** — Compare extracted snapshot against stored knowledge
3. **DETECT** — Classify findings (new, drifted, stale, contradicting) by severity
4. **REMEDIATE** — Surface enrichment prompts; stage high-confidence extractions for human review

Runs until drift score converges below threshold.

### Maintenance Burden Mitigation

The system is designed to minimize human effort:

| Activity                             | Who Does It           | Frequency            | Effort       |
| ------------------------------------ | --------------------- | -------------------- | ------------ |
| Auto-extraction from code/connectors | System (pipeline)     | On sync/schedule     | Zero         |
| Staging high-confidence extractions  | System (pipeline)     | On sync              | Zero         |
| Reviewing staged knowledge           | Human (PR review)     | Weekly or on-demand  | ~15 min/week |
| Writing strategic narratives         | Human (author)        | Per major initiative | ~30 min each |
| Correcting wrong extractions         | Human (reject staged) | As surfaced          | ~2 min each  |
| Drift detection                      | System (pipeline)     | On schedule          | Zero         |
| Responding to drift alerts           | Human (verify/update) | As surfaced          | ~5 min each  |

**Target:** <30 minutes/week of human maintenance for a well-bootstrapped knowledge base. The pipeline does the detection; humans only decide.

### Integration Points

| Component         | File                                                        | Change                             |
| ----------------- | ----------------------------------------------------------- | ---------------------------------- |
| Graph types       | `packages/graph/src/types.ts:5-87`                          | Add 5 node types, 2 edge types     |
| Serializer        | `packages/graph/src/store/Serializer.ts:5`                  | Bump schema version                |
| Ingestor dispatch | `packages/cli/src/mcp/tools/graph/ingest-source.ts:14,52`   | Add `'business'` source            |
| MCP resources     | `packages/cli/src/mcp/server.ts:284-355`                    | Add `harness://business-knowledge` |
| gather_context    | `packages/cli/src/mcp/tools/gather-context.ts:121,282`      | Add business knowledge constituent |
| Phase mapping     | `packages/graph/src/context/Assembler.ts:34-39`             | Add business types per phase       |
| Session sections  | `packages/types/src/session-state.ts:15-22`                 | Add `businessContext` section      |
| Health signals    | `packages/cli/src/skill/recommendation-types.ts:5-36`       | Add business signals               |
| Connector utils   | `packages/graph/src/ingest/connectors/ConnectorUtils.ts:41` | Configurable truncation            |

**New files:**

- `packages/graph/src/ingest/BusinessKnowledgeIngestor.ts`
- `packages/graph/src/ingest/KnowledgeLinker.ts`
- `packages/graph/src/ingest/DiagramParser.ts`
- `packages/cli/src/mcp/resources/business-knowledge.ts`
- Knowledge pipeline skill definition (follows docs-pipeline pattern)
- Code signal extractors (test descriptions, enums, validators, API paths)

### Phased Delivery

**Phase 1 (Weeks 1-3): Foundation**

- Graph schema extensions (new node/edge types)
- `BusinessKnowledgeIngestor` reading from `docs/knowledge/`
- `harness://business-knowledge` MCP resource
- `gather_context` integration
- Manual authoring for 1-2 pilot domains

**Phase 2 (Weeks 4-6): Code Extractors**

- Test description extractor
- Enum/constant extractor
- Validation rule extractor
- API path extractor
- `.harness/knowledge/extracted/` output format

**Phase 3 (Weeks 7-9): Connector Enhancement**

- Raise truncation limits (configurable)
- Jira: comments, custom fields, acceptance criteria
- Confluence: full content, page hierarchy, labels
- Slack: thread structure, reaction patterns
- KnowledgeLinker post-processing pass

**Phase 4 (Weeks 10-12): Pipeline + Diagrams**

- `/harness:knowledge-pipeline` skill (4-phase convergence loop)
- Diagram-as-code parser (Mermaid/D2/PlantUML)
- Staging workflow (`.harness/knowledge/staged/`)
- Drift detection and gap reporting

**Phase 5 (Future): Visual + Advanced**

- Vision model analysis of image attachments
- Design tool API connectors (Figma, Miro)
- Cross-source contradiction detection
- Knowledge coverage scoring per domain

## Alternatives Considered

### Option A: Manual Authoring Only

Business knowledge authored entirely in markdown files, ingested by a new ingestor, validated by a pipeline.

**Why not chosen:** Cold start problem — the system provides no value until humans invest significant time writing knowledge files. Adoption risk is high because the authoring burden falls entirely on humans. The 60-70% of knowledge that can be auto-extracted from existing systems would go uncaptured.

### Option C: Full Multimodal Knowledge Hub

Everything in the chosen option plus vision model analysis of image attachments, design tool API connectors (Figma, Miro), and comprehensive cross-source ontology management.

**Why not chosen:** Scope is too large for initial delivery (16-24 weeks). Vision model accuracy on complex diagrams is uncertain. Design tool APIs change frequently and add maintenance burden. The chosen option naturally evolves into this if visual knowledge proves valuable — diagram-as-code parsing is included as the lowest-cost entry point.

## Consequences

### Positive

- Skills become business-aware by default — architecture advisor weighs compliance, code review flags business-critical changes, planning considers revenue impact
- ~60-70% of atomic business knowledge bootstrapped automatically from existing Jira/Slack/Confluence/code signals
- Knowledge stays fresh via pipeline drift detection — no silent rot
- Low maintenance burden (<30 min/week) once bootstrapped
- Dual-location model keeps `docs/` clean and authoritative while giving the system a staging area
- Follows existing patterns (ingestor, linker, pipeline, MCP resource) — no architectural novelty needed
- Incrementally deliverable — value at each phase

### Negative

- Auto-extraction will produce false positives — needs confidence calibration over time (mitigation: staged review, human promotion gate)
- Adds complexity to the graph schema and context assembly — more node types competing for token budget (mitigation: phase-aware filtering already handles this via Assembler)
- Requires API keys for external connectors to provide full value (mitigation: graceful degradation — code extractors work without any external access)
- KnowledgeLinker is a new subsystem that needs maintenance (mitigation: follows TopologicalLinker pattern, tested in isolation)

### Neutral

- Graph schema version bumps from 1 to 2 — one-time migration
- Existing skills don't need changes to benefit — they already consume graph context via gather_context/Assembler; new business nodes surface automatically through the existing phase-mapping mechanism
- The knowledge pipeline skill follows the docs-pipeline pattern — new skill, but familiar architecture

## Action Items

- [ ] Define graph schema extensions (node types, edge types) — owner: TBD — by: Phase 1
- [ ] Implement BusinessKnowledgeIngestor for `docs/knowledge/` — owner: TBD — by: Phase 1
- [ ] Add `harness://business-knowledge` MCP resource — owner: TBD — by: Phase 1
- [ ] Wire business knowledge into `gather_context` — owner: TBD — by: Phase 1
- [ ] Author pilot business knowledge for 1-2 domains — owner: Chad — by: Phase 1
- [ ] Implement code signal extractors (test descriptions, enums, validators) — owner: TBD — by: Phase 2
- [ ] Enhance connectors (truncation, comments, hierarchy) — owner: TBD — by: Phase 3
- [ ] Implement KnowledgeLinker post-processing — owner: TBD — by: Phase 3
- [ ] Build `/harness:knowledge-pipeline` skill — owner: TBD — by: Phase 4
- [ ] Implement diagram-as-code parser — owner: TBD — by: Phase 4
