# Feature Spec: Cross-Feature Knowledge Graph (AOP)

> **Purpose of this document**: Define implementation-ready delivery for Q10 and record the architectural decision to defer the original Q12 post-merge canary design now that the shared merge reconciler exists.

**Version:** 2.0  
**Date:** 2026-03-16  
**Status:** Draft (Q10 Active, Q12 Deferred)  
**Roadmap Mapping:** M38

---

## 0. Scope and Decision Record

### 0.1 In-Scope

This spec implements:

- **Q10** Cross-Feature Knowledge Graph

### 0.2 Deferred From This Spec

This spec does **not** implement the original Q12 "post-merge canary verification" flow.

Decision:

- the current shared reconciler already addresses the primary risk class that the old canary design was trying to mitigate: mainline divergence that only becomes visible when reconciling a feature against updated mainline state.
- the current merge path already requires required gate modes to pass before merge promotion.
- the old Q12 design added a heavyweight post-merge blocked-state lifecycle that now overlaps with the reconciler's purpose while also conflicting with current merge cleanup semantics.

Therefore:

- **Q12 is deferred** from M38 in its original form.
- if the project later proves a need for true merged-head-only verification, that should be specified as a separate, smaller feature focused on merged-head confirmation before cleanup, not as the original blocked-after-merge canary workflow.

### 0.3 Constraints

- knowledge retrieval MUST be deterministic and auditable
- no vector DB dependency in this phase
- no AI ranking/reranking in first iteration
- merged feature cleanup MUST NOT destroy the historical facts needed for deterministic retrieval

### 0.4 Current Project State

This spec was audited against the live repository on 2026-03-16.

Current status:

1. **Q10 is still unimplemented.**
   - there is no `knowledge.search` tool, no knowledge graph service, and no persisted knowledge graph artifact today.

2. **The reconciler materially changes the old Q12 tradeoff.**
   - mainline divergence is already routed into the shared reconciler lane.
   - reconciler guidance already requires verification via `gates.run` fast mode, with escalation to fuller verification when needed.
   - this leaves only a narrow "true merged-head-only" risk class for any future Q12 replacement.

3. **Current merge cleanup matters for Q10.**
   - `MergeService.featureReadyToMerge()` can immediately delete `.aop/features/<feature_id>` when `cleanup.auto_after_merge=true` and `grace_period_seconds<=0`.
   - Q10 therefore cannot assume merged feature artifacts remain on disk indefinitely.
   - implementation MUST define a deterministic retention/snapshot rule before enabling Q10.

4. **Replay exists and may be consumed, but evidence-integrity and doctor remain optional future inputs.**
   - replay timeline is implemented and is available as an auditable historical source.
   - evidence-integrity and doctor work remain outstanding and MUST NOT be required for Q10 v1.

### 0.5 Current Architecture Wiring Requirements

Implementation must update the current contract surfaces, not older pre-refactor seams:

- `agentic/orchestrator/defaults/policy.defaults.yaml`
- `agentic/orchestrator/schemas/policy.schema.json`
- `agentic/orchestrator/schemas/policy.user.schema.json`
- `apps/control-plane/src/core/constants.ts`
- `apps/control-plane/src/application/tools/tool-metadata.ts`
- `apps/control-plane/src/core/kernel.ts`
- `apps/control-plane/src/application/kernel-tool-wiring.ts`
- `agentic/orchestrator/tools/catalog.json`
- regenerated `agentic/orchestrator/tools.md`

---

## 1. Objectives

### 1.1 Must-Have Outcomes

- planner/orchestrator can retrieve prior feature patterns such as collisions, mitigations, gate failures, and dependency history to improve plan quality
- historical retrieval remains deterministic, bounded, and auditable
- the feature remains opt-in and backward compatible

### 1.2 Non-Goals

- no live semantic search or embedding pipeline
- no autonomous planner prompt rewriting
- no post-merge canary state machine in this milestone

---

## 2. Architecture Decisions

### 2.1 Graph as Derived Runtime Artifact

Knowledge graph is deterministic derived state from canonical runtime artifacts such as:

- `state.md`
- `plan.json`
- decisions and logs
- gate evidence
- collisions
- dependency-blocking data
- replay timeline entries
- merge-time summaries persisted for retention

It is not manually edited.

### 2.2 Retention Before Cleanup

Because merged feature directories may be auto-cleaned, the graph builder MUST NOT rely on long-term presence of `.aop/features/<id>` after merge.

Implementation MUST choose one of these deterministic patterns:

1. persist graph facts directly into `.aop/knowledge/graph.json` before cleanup can remove the source feature directory, or
2. persist a smaller merge-time rollup artifact under `.aop/runtime/**` or `.aop/knowledge/**` and build the graph from those retained summaries plus live non-terminal feature artifacts.

Whichever pattern is chosen, the retained inputs must be:

- schema-backed
- append-safe or lock-safe
- reconstructable deterministically from canonical runtime state at the time they were captured

### 2.3 Controlled Retrieval API

Knowledge access is through explicit tool/query APIs with bounded filters and deterministic ranking rules. Search results must be explainable from persisted graph content, not opaque scoring heuristics.

### 2.4 Q12 Replacement Guidance

The original canary concept is intentionally not carried forward here.

If a future follow-up is required, it should target:

- merged-head-only regressions that neither pre-merge gates nor the reconciler already cover
- a small verification step before cleanup/final confirmation
- no new long-lived `blocked-after-merge` lifecycle unless a concrete operational need is proven

---

## 3. Contracts and Artifacts

### 3.1 Knowledge Graph Artifact

```text
.aop/knowledge/graph.json
```

Node contract:

```json
{
  "id": "node:feature:payment_retry_guard",
  "type": "feature",
  "labels": ["payments", "retry"],
  "attrs": {
    "status": "merged",
    "created_at": "2026-03-01T11:00:00Z"
  }
}
```

Edge contract:

```json
{
  "id": "edge:blocked_by:feature_a:feature_b",
  "type": "blocked_by",
  "from": "node:feature:feature_a",
  "to": "node:feature:feature_b",
  "attrs": {
    "reason": "openapi_operation_conflict"
  }
}
```

### 3.2 New MCP Tool

- `knowledge.search`

No `merge.canary_verify` tool is defined by this revision.

### 3.3 Optional Policy Additions

```yaml
innovation:
  knowledge_graph: false

knowledge:
  enabled: false
  planner_context:
    enabled: false
    max_results: 5
  retention:
    mode: graph_snapshot # graph_snapshot | merge_rollup
```

Rules:

- all toggles default to `false`
- `innovation.knowledge_graph` and `knowledge.enabled` must both be `true` before graph build/search is active
- `planner_context.enabled` only affects whether planner context is enriched; it does not change graph generation semantics

---

## 4. Detailed Feature Spec

## 4.1 Q10: Cross-Feature Knowledge Graph

### 4.1.1 Problem

Historical delivery knowledge exists but is difficult to query and reuse during planning, especially once merged feature directories have been cleaned up.

### 4.1.2 Design

Build and maintain a deterministic graph from canonical runtime artifacts and retained merge-time summaries, then expose a deterministic search API.

### 4.1.3 Node Types

- `feature`
- `file`
- `lock_resource`
- `collision`
- `gate_failure`
- `mitigation_pattern`
- `dependency`

### 4.1.4 Edge Types

- `touches`
- `blocked_by`
- `fixed_by`
- `depends_on`
- `reuses_pattern`
- `failed_gate_on`

### 4.1.5 Ranking Rules (Deterministic)

Ranking by tuple order:

1. exact feature/status/type match
2. recency descending
3. frequency of relevant edge types
4. lexicographic node id

### 4.1.6 Query Contract

Input (`knowledge.search`):

```json
{
  "query": "db migration retry lock",
  "feature_id": "payment_retry_guard",
  "limit": 20,
  "filters": {
    "node_types": ["mitigation_pattern", "gate_failure"]
  }
}
```

Output:

```json
{
  "results": [
    {
      "node_id": "node:mitigation:retry_lock_backoff",
      "score": 0.89,
      "evidence_refs": [".aop/features/legacy_feature/evidence/gates/full-2026-02-20.json"]
    }
  ]
}
```

### 4.1.7 File Targets

- `apps/control-plane/src/application/services/knowledge-graph-service.ts` (new)
- `apps/control-plane/src/application/services/plan-service.ts`
- `apps/control-plane/src/supervisor/planning-wave-executor.ts`
- `apps/control-plane/src/application/services/merge-service.ts`
- `apps/control-plane/src/core/path-layout.ts`
- `apps/control-plane/src/core/constants.ts`
- `apps/control-plane/src/application/tools/tool-metadata.ts`
- `agentic/orchestrator/defaults/policy.defaults.yaml`
- `agentic/orchestrator/schemas/policy.schema.json`
- `agentic/orchestrator/schemas/policy.user.schema.json`
- `agentic/orchestrator/tools/catalog.json`
- `agentic/orchestrator/tools/schemas/input/knowledge.search.input.schema.json` (new)
- `agentic/orchestrator/tools/schemas/output/knowledge.search.output.schema.json` (new)

### 4.1.8 Acceptance Criteria

- graph generated or updated deterministically from canonical sources plus the selected retention mechanism
- search returns stable ordering for the same query and graph state
- planner can consume top results as an optional context bundle extension
- merged-feature cleanup does not destroy the historical facts required for future deterministic search

---

## 5. Milestones

### KG1: Graph Foundation

Tasks:

1. implement graph model/service and build/update pipeline
2. define and implement the retention boundary so graph facts survive current auto-cleanup behavior
3. add search tool contracts and query API

Exit gate:

- graph file and search output are deterministic under repeated runs

### KG2: Planner Context Integration

Tasks:

1. wire optional knowledge retrieval into the planner context bundle
2. add policy toggles for knowledge graph generation and planner enrichment usage

Exit gate:

- planner receives contextual patterns without changing core deterministic flow when the feature is disabled

---

## 6. Testing Strategy (Normative)

### 6.1 Unit Tests

- graph node/edge dedup and deterministic sort order
- knowledge ranking stability for fixed input
- retention/snapshot path preserves graph facts across cleanup

### 6.2 Integration Tests

- graph updates after feature lifecycle events
- `knowledge.search` returns expected patterns for seeded artifacts
- merged feature cleanup still leaves graph/search data intact

### 6.3 Transport Parity

- `knowledge.search` parity (in-process vs MCP)

---

## 7. Acceptance Criteria

1. Knowledge graph is built and queryable with deterministic ranking.
2. Planner can consume knowledge results in controlled opt-in mode.
3. Merge cleanup, feature deletion, and retained-history behavior remain deterministic under the selected retention strategy.
4. New tools, schemas, and policies validate and pass all quality gates.
5. Q12 remains explicitly deferred by this spec revision; no hidden canary workflow is introduced indirectly.

---

## 8. Risks and Mitigations

- Risk: graph growth impacts performance.
  - Mitigation: bounded compaction and deterministic archival windows.

- Risk: noisy knowledge retrieval overwhelms planner context.
  - Mitigation: strict limit/filter controls and deterministic top-K selection.

- Risk: existing auto-cleanup removes feature artifacts before Q10 can persist the data it needs.
  - Mitigation: explicit merge-time summary persistence plus cleanup ordering rules that run only after graph artifacts are durable.

- Risk: teams infer that Q12 still exists because of the legacy filename.
  - Mitigation: this revision explicitly marks Q12 deferred and restricts all concrete implementation work in the document to Q10.

---

## 9. Definition of Done

A completed KG milestone MUST include:

- changed files and rationale
- policy/schema/tool catalog diffs
- integration and parity tests
- command verification summary
- `spec-files/progress.md` update with residual tasks (if any)
