DOC3_Companion_Doc_Delta_Plan_R9_2_Canonical.md
Current Specs/DOC3/DOC3_Companion_Doc_Delta_Plan_R9_2_Canonical.md
ELNOR REPO READER TEXT MIRROR
Original path: Current Specs/DOC3/DOC3_Companion_Doc_Delta_Plan_R9_2_Canonical.md
Source repo: /Users/OpenClaw1/Elnor/Elnor Specs
Git branch: main
Git commit: dbaa25962edc11ab30e8d4ca1715f9ae5bf77331
Generated: 2026-06-09T01:23:58.539Z
---
# DOC3 Companion Doc Delta Plan — R9.2 [Canonical Consolidated]
## Revision Lineage (must persist in all later versions)
Based on:
- DOC3 Companion Doc Delta Plan — R9.1 [Canonical Consolidated]
- DOC3_FINAL_SELF_CONTAINED_REDLINE_R3_2
- integrated multi-round red-team review, adjudication, self-audit, and production-flattening decisions covering:
- owner-doc closure for learning, checkpointing, routing, MCP/M365, Acrobat, import, catalog, and availability surfaces
- exact Q, DOC4, DOC10, DOC11, DOC12, DOC15, DOC1, DOC8, DOC9, DOC2, and DOC13 obligations
- control-backing, read-surface backing, non-phantom UI, and partial-deployment truth requirements
This consolidated version fully supersedes DOC3 Companion Doc Delta Plan — R9.1 as the operative companion-delta specification.
## Consolidation Rule
This file is the current **single operative DOC3 companion delta plan**.
If any preserved historical content below conflicts with **Part 0 — R9.2 Canonical Owner-Doc Reconciliation, Contract Completion, and Production Hardening**, Part 0 governs.
## Included Source Chain
- 1. Inherited Baseline — DOC3 Companion Doc Delta Plan — R9.1 [Canonical Consolidated]
- 2. Integrated Production Revision — R9.2 Canonical Owner-Doc Reconciliation, Contract Completion, and Production Hardening
## Canonicalization Note
R9.2 carries the accepted DOC3 cross-document obligations directly into the operative companion body. No Appendix-only companion obligation remains authoritative after this merge.
---
# Part 0 — R9.2 Canonical Owner-Doc Reconciliation, Contract Completion, and Production Hardening
## §0D Purpose
R9 recognized most of the right cross-doc dependencies, but the preserved merge history still leaves too many opportunities for coding agents to drift when choosing:
- which schema is authoritative,
- which artifact path is canonical,
- which doc owns a contract,
- and which UI labels should survive into the user experience.
R9.2 fixes that by explicitly flattening the highest-risk areas and carrying the accepted cross-doc obligations into the canonical body.
## §0D.1 Global cross-doc rules (authoritative)
1. **One schema name = one canonical definition**
2. **One artifact kind = one canonical path**
3. **One runtime lifecycle = one canonical route family**
4. **Teach is a user-facing action; LearnSession is the canonical runtime object**
5. **Pending Abilities is the only primary user-facing umbrella for not-yet-promoted learned abilities**
6. **"Experimental" remains an internal install-lane idea only; it is not a required primary UI category**
7. **Rehearsal policy replaces a mandatory full sandbox requirement**
8. **Owner docs must absorb these deltas over time; this companion remains operative only until the owner docs are flattened**
## §0D.2 Owner-doc table (authoritative)
| Contract / concern | Owner doc | Consumers |
|---|---|---|
| LearnSession runtime object | DOC3 | DOC10, DOC11, DOC12, Q UI, Core |
| LearningRuntimeSnapshot | DOC3 | DOC10, DOC11, Q UI |
| ObservationScopeRuntime | DOC3 | DOC11, Q UI |
| SemanticWorkflowInterpretation | DOC3 | DOC15, Q UI, Core |
| ValidationRun / ValidationStepResult | DOC3 | DOC9, DOC15, Q UI |
| Ability Availability Snapshot | DOC3 (emitted by EC, informed by DOC11 runtime truth) | DOC10, Q UI |
| Ability lookup contract | DOC3 | DOC10, Q UI |
| Single-writer configuration intent | DOC3 + Core | DOC4, DOC9 |
| Project/work-object semantic identity | Core / DOC7 | DOC3, MCP layers, retrieval providers |
| MCP provider registry / policy / health | DOC3 operational layer | DOC10, DOC11, Q UI |
| LlamaIndex sidecar contracts | DOC18 | DOC3, DOC10, DOC11, DOC2, Q UI |
| Learn UI naming / states | DOC3 + Q UI | Q UI |
| `AbilityAvailabilityEntrySchema` / `AbilityAvailabilitySnapshotSchema` | DOC3 | DOC10, DOC11, Q UI |
| `SkillCatalogCurrentSchema` | DOC3 | Q UI |
| `LearnSessionDetailResponseSchema` | DOC3 | Q UI |
| `ProposalDetailResponseSchema` | DOC3 | Q UI |
| `CheckpointLintReportSchema` | DOC3 | Q UI, DOC15, DOC9 |
| MCP smoke-test / auth challenge route contracts | DOC3 + DOC4 | Q UI, DOC11 |
| Connector receipt identity assertion fields | DOC3 | Q UI, DOC11 |
## §0D.3 Canonical artifact paths (authoritative)
Use these paths only:
```text
ELNOR_MEMORY/system/learning/runtime/current.json
ELNOR_MEMORY/system/learning/runtime/observation_scope_current.json
ELNOR_MEMORY/system/learning/interpretations/<interpretation_id>.json
ELNOR_MEMORY/system/learning/validation_runs.jsonl
ELNOR_MEMORY/system/learning/validation_step_results.jsonl
ELNOR_MEMORY/system/learning/receipts.jsonl
ELNOR_MEMORY/system/abilities/availability_current.json
ELNOR_MEMORY/system/capabilities/bridge_entries_current.json
ELNOR_MEMORY/system/mcp/servers_current.json
ELNOR_MEMORY/system/mcp/policy_current.json
ELNOR_MEMORY/system/mcp/health_current.json
ELNOR_MEMORY/system/learning/install_sagas.jsonl
ELNOR_MEMORY/system/learning/views/active_current.json
ELNOR_MEMORY/system/learning/views/pending_current.json
ELNOR_MEMORY/system/learning/views/history_current.json
ELNOR_MEMORY/system/learning/views/receipts_current.json
ELNOR_MEMORY/system/learning/views/partial_deployment_current.json
ELNOR_MEMORY/system/learning/observations/
ELNOR_MEMORY/system/abilities/catalog_current.json
```
### Explicit deprecation
Do not create parallel current-truth artifacts for:
- ability availability under orchestration-specific paths,
- learning receipts under multiple namespaces,
- MCP registry/policy under multiple current-path spellings.
## §0D.4 Canonical route families (authoritative)
### Learning
```http
POST /api/learn/sessions
POST /api/learn/sessions/:sessionId/start
POST /api/learn/sessions/:sessionId/pause
POST /api/learn/sessions/:sessionId/stop
POST /api/learn/sessions/:sessionId/cancel
POST /api/learn/sessions/:sessionId/answer-questions
POST /api/learn/sessions/:sessionId/set-test-policy
GET /api/learn/runtime/current
GET /api/learn/sessions/:sessionId/observation-scope
GET /api/learn/sessions/:sessionId/detail
GET /api/learn/proposals/:proposalId/detail
GET /api/learn/proposals/:proposalId/validation-runs
POST /api/learn/proposals/:proposalId/revise
POST /api/learn/proposals/:proposalId/validate
POST /api/learn/proposals/:proposalId/install
```
### Ability availability / lookup
```http
GET /api/abilities/availability
GET /api/abilities/:abilityId/availability
POST /api/abilities/lookup
POST /api/abilities/explain-match
```
### MCP policy / registry
```http
GET /api/mcp/servers
GET /api/mcp/policy
GET /api/mcp/health
POST /api/mcp/policy/provider/:provider
POST /api/mcp/policy/server/:serverId
```
## §0D.5 Learn UI naming (authoritative cross-doc rule)
The authoritative user-facing structure is:
### Navigation
**Abilities**
- Skills
- Connectors
- Learn
### Learn page title
**Ability Learning**
### Learn page tabs
- Learn New Ability
- Active Capability Learning
- Pending Abilities
- History
### Learn New Ability cards
- Demonstrating Skill
- Coaching Agent
- Autonomous Agent Practice
- Improving Existing Skill
- Import Skill
### Contextual shortcuts
- Learn From This
- Use as Example
- Improve This Skill
- Watch My Actions (capture option only)
### Explicit rule
Q UI, DOC3, and companion references must not require a primary user-facing category called:
- Experimental
- Experimental Abilities
- Private Trial Skill
- Learning Center
## §0D.6 TeachSession deprecation rule
Any retained legacy mention of `TeachSession` in companion/owner docs should be interpreted as:
- a historical alias,
- or a UI trigger concept,
- not a separate canonical runtime object.
The canonical runtime object is `LearnSession`.
## §0D.7 Rehearsal policy rule
Owner docs should use **Test Policy / Rehearsal Policy** language instead of assuming a full mandatory sandbox model for every app family.
This is especially important for:
- DAW-class apps,
- hardware-coupled apps,
- local desktop apps with non-virtualizable dependencies.
---
## §0E Required owner-doc changes for the next flattened revisions
### §0E.1 DOC3
Must absorb:
- user-facing Learn naming cleanup
- LearnSession canonicalization
- LearningRuntimeSnapshot
- ObservationScopeRuntime
- SemanticWorkflowInterpretation
- ValidationRun / ValidationStepResult
- Ability availability and lookup contracts
- rehearsal policy
- pending-abilities UI semantics
### §0E.2 DOC7 / Core
Must continue to own:
- project/work-object identity
- alias resolution
- bucket support/pointers
- not DOC3
DOC3 may consume project bindings but must not redefine project truth.
### §0E.3 DOC10
Must consume:
- one bridge entry path,
- one ability availability path,
- one lookup contract,
- and one learn/runtime snapshot path.
It must not define parallel copies.
### §0E.4 DOC11
Must provide runtime-usable-now inputs for:
- ability availability
- observation adapter health
- connector health
- browser relay detachment
- local runtime degradations
### §0E.5 DOC15
Must consume:
- SemanticWorkflowInterpretation
- Validation outcomes
- support-pack usefulness
- generated-skill usefulness
- later-use activation evidence
### §0E.6 Q UI
Must align its labels and sections with §0D.5 and stop requiring "Experimental" as a top-level learn category.
## §0D.4A MCP, Acrobat, learn-read, skill-import, trigger-test, packs, and category route families added by this revision (authoritative)
### Public EC management/read-model routes Q may call
```http
GET /api/mcp/servers
POST /api/mcp/servers/register
PATCH /api/mcp/servers/:serverId
DELETE /api/mcp/servers/:serverId
GET /api/mcp/servers/:serverId/health
GET /api/mcp/servers/:serverId/auth/status
POST /api/mcp/servers/:serverId/auth/start
GET /api/mcp/servers/:serverId/auth/callback
POST /api/mcp/servers/:serverId/auth/refresh
POST /api/mcp/servers/:serverId/auth/revoke
POST /api/mcp/servers/:serverId/smoke-test
GET /api/mcp/auth-profiles
POST /api/mcp/auth-profiles
PATCH /api/mcp/auth-profiles/:authProfileId
DELETE /api/mcp/auth-profiles/:authProfileId
POST /api/mcp/policy/update
GET /api/mcp/receipts
GET /api/mcp/ask-first/pending
POST /api/mcp/ask-first/:dispatchId/approve
POST /api/mcp/ask-first/:dispatchId/deny
POST /api/mcp/auth/challenge/respond
GET /api/adapters/acrobat/health
POST /api/adapters/acrobat/extract-text
POST /api/adapters/acrobat/extract-tables
POST /api/adapters/acrobat/ocr
POST /api/adapters/acrobat/redaction-prep
POST /api/skills/import/uploads
DELETE /api/skills/import/uploads/:tempArtifactRef
POST /api/skills/import/scan
POST /api/skills/import/stage
POST /api/skills/import/approve
POST /api/skills/import/reject
POST /api/skills/import/install-private
POST /api/skills/import/discard
POST /api/skills/import/retry
GET /api/skills/import/:importId
GET /api/skills/import/list
POST /api/skills/trigger-test
GET /api/skills/packs
GET /api/learn/sessions
GET /api/learn/sessions/:sessionId/detail
GET /api/learn/sessions/:sessionId/events
GET /api/learn/sessions/:sessionId/observation-scope
GET /api/learn/sessions/:sessionId/checkpoint-receipts
GET /api/learn/proposals
GET /api/learn/proposals/:proposalId/detail
GET /api/learn/proposals/:proposalId/validation-runs
GET /api/learn/history
GET /api/learn/receipts
POST /api/categories
PUT /api/categories/:categoryId
DELETE /api/categories/:categoryId
POST /api/categories/:categoryId/assign
DELETE /api/categories/:categoryId/items/:itemKind/:itemId
```
### Shared internal contracts that Q must not call directly
The following remain shared internal contracts consumed by DOC4 / DOC11 / OpenClaw dispatch layers and must **not** be exposed as one public route per tool family:
- `M365OperationRequestSchema`
- `M365OperationResponseSchema`
### Named response bindings Q must use
Q and companion docs must bind to the authoritative named request/response schemas exactly as follows:
| Route family | Request schema | Success response |
|---|---|---|
| MCP register / patch | `MCPServerCreateRequestSchema` / `MCPServerPatchRequestSchema` | `MCPServerMutationResponseSchema` |
| MCP auth start | `MCPAuthStartRequestSchema` | `MCPAuthStartResponseSchema` |
| MCP auth callback | `MCPAuthCallbackQuerySchema` | `MCPServerAuthStatusSchema` |
| MCP auth refresh | `MCPAuthRefreshRequestSchema` | `MCPServerAuthStatusSchema` |
| MCP auth revoke | `MCPAuthRevokeRequestSchema` | `MCPAuthRevokeResponseSchema` |
| MCP smoke test | `MCPSmokeTestRequestSchema` | `MCPSmokeTestResponseSchema` |
| MCP auth challenge respond | `MCPAuthChallengeRespondRequestSchema` | `MCPAuthChallengeRespondResponseSchema` |
| Skill import read/list | none | `SkillImportDetailResponseSchema` / `SkillImportListResponseSchema` |
| Trigger test | `SkillTriggerTestRequestSchema` | `SkillTriggerTestResponseSchema` |
| Skill packs | none | `SkillPacksListResponseSchema` |
| Learn read/detail/history/receipts | none | named Learn read schemas from `§2.3A` |
| Category remove assignment | none | `CategoryDeleteAssignmentResponseSchema` |
### Canonical artifact paths to add
Add the following artifact paths to `§0D.3 Canonical artifact paths`:
```text
ELNOR_MEMORY/system/mcp/servers/registry.jsonl
ELNOR_MEMORY/system/mcp/servers/current.json
ELNOR_MEMORY/system/mcp/auth_profiles/history.jsonl
ELNOR_MEMORY/system/mcp/auth_profiles/current.json
ELNOR_MEMORY/system/mcp/ask_first/pending.jsonl
ELNOR_MEMORY/system/mcp/ask_first/current.json
ELNOR_MEMORY/system/mcp/receipts/receipts.jsonl
ELNOR_MEMORY/system/adapters/acrobat/current.json
ELNOR_MEMORY/system/adapters/acrobat/receipts.jsonl
ELNOR_MEMORY/system/skills/import_uploads/
ELNOR_MEMORY/system/skills/imports/history.jsonl
ELNOR_MEMORY/system/skills/imports/current.json
ELNOR_MEMORY/system/skills/packs/current.json
ELNOR_MEMORY/system/categories/history.jsonl
ELNOR_MEMORY/system/categories/current.json
```
### Required module-path changes
Replace the active module list so that it **removes** the custom ELNOR wrapper modules and **adds** the following active paths:
```text
apps/ec-service/src/routes/mcp-manage-routes.ts
apps/ec-service/src/routes/mcp-auth-routes.ts
apps/ec-service/src/routes/mcp-ask-first-routes.ts
apps/ec-service/src/routes/acrobat-routes.ts
apps/ec-service/src/routes/skill-import-routes.ts
apps/ec-service/src/routes/learn-read-routes.ts
apps/ec-service/src/routes/category-routes.ts
apps/ec-service/src/mcp/mcp-registry-service.ts
apps/ec-service/src/mcp/mcp-auth-service.ts
apps/ec-service/src/mcp/mcp-ask-first-service.ts
apps/ec-service/src/adapters/acrobat-service.ts
apps/ec-service/src/skills/import-upload-service.ts
apps/ec-service/src/skills/trigger-test-service.ts
apps/ec-service/src/skills/packs-service.ts
apps/ec-service/src/categories/category-service.ts
```
Remove from required active scope:
```text
apps/ec-service/src/mcp-servers/project-server.ts
apps/ec-service/src/mcp-servers/knowledge-server.ts
apps/ec-service/src/mcp-servers/local-files-server.ts
apps/ec-service/src/mcp-servers/admin-health-server.ts
```
### Non-phantom UI rule for removed custom wrappers
Q must not show connector/server cards, toggle rows, install affordances, or health chips for the removed custom ELNOR wrappers.
### Acrobat active-surface rule
Because Acrobat is active in DOC3:
- Q must show Acrobat only when `GET /api/adapters/acrobat/health` exists,
- button enabled/disabled state must follow backend health,
- and redaction-prep must be wired through ask-first or blocked state, not optimistic UI.
## §0E.7 Shared package additions required (R11.2 comprehensive)
All of these must exist in `packages/contracts/src/`:
```text
learning/learn-session.ts
learning/create-learn-session.ts
learning/runtime-snapshot.ts
learning/observation-scope-runtime.ts
learning/semantic-workflow-interpretation.ts
learning/validation-run.ts
learning/test-policy.ts
learning/lifecycle-event.ts
learning/receipts.ts
learning/checkpoint-receipt.ts
learning/observation-adapter.ts
learning/observed-action.ts
learning/boundary.ts
learning/route-contracts.ts
learning/pending-ability-ui-state.ts
abilities/lookup.ts
search/provider-kind.ts
common/category.ts
```
---
## §0E.8 Frontend modules to rename or create
Required / preferred names:
```text
apps/q-frontend/src/features/learn/AbilityLearningPage.tsx
apps/q-frontend/src/features/learn/ActiveCapabilityLearningView.tsx
apps/q-frontend/src/features/learn/PendingAbilitiesView.tsx
apps/q-frontend/src/features/learn/LearnHistoryView.tsx
apps/q-frontend/src/features/learn/LearnProposalDetail.tsx
apps/q-frontend/src/features/learn/LearnSessionDetail.tsx
```
Avoid making `ExperimentalLearnedAbilitiesView.tsx` the canonical user-facing concept going forward.
## §0E.9 Partial deployment rules (authoritative)
If R11.2 / R9.2 surfaces ship before all owner-doc revisions:
- Q must show `degraded` / `not yet available` rather than inventing state
- DOC10 must prefer absent/unavailable over guessed availability
- Learn UI must disable actions whose backing routes are not deployed
- private installs must not claim later-use readiness until `availability_current.json` exists and is fresh
---
## §0E.10 DOC4 / DOC11 — verify_checkpoint bridge tool
### New bridge tool (add to DOC4 bridge route list and DOC11 runtime tool catalog)
```json
{
"name": "verify_checkpoint",
"description": "Call voluntarily when you believe you have reached a semantic checkpoint in a guided skill. This is guidance, not a forced state machine — skip checkpoints freely if a better path exists. Every call emits a receipt to EC for learning and repair signals.",
"parameters": {
"type": "object",
"properties": {
"checkpoint_id": {
"type": "string",
"description": "The checkpoint_id from the skill's checkpoint manifest."
},
"status": {
"type": "string",
"enum": ["reached", "skipped", "failed"],
"description": "Whether the checkpoint was reached, deliberately skipped, or attempted and failed."
},
"evidence": {
"type": "string",
"description": "What the agent observed that led to this status determination. E.g., 'Export dialog is visible with PDF selected' or 'No export dialog appeared after 10 seconds'."
},
"reason": {
"type": "string",
"description": "Why the checkpoint was skipped or failed. Required for skipped/failed; optional for reached."
}
},
"required": ["checkpoint_id", "status", "evidence"]
}
}
```
### EC handler contract
```ts
// apps/ec-service/src/learning/handle-checkpoint-verification.ts
import { z } from "zod";
import { CheckpointVerificationReceiptSchema } from "@elnor/contracts/learning/checkpoint-receipt";
import { v4 as uuidv4 } from "uuid";
export interface HandleCheckpointVerificationInput {
checkpoint_id: string;
status: "reached" | "skipped" | "failed";
evidence: string;
reason?: string;
// Context injected by the bridge router:
learn_session_id?: string;
ability_id?: string;
dispatch_id?: string;
agent_id?: string;
room_id?: string;
}
export interface HandleCheckpointVerificationOutput {
receipt_id: string;
accepted: boolean;
}
export async function handleCheckpointVerification(
input: HandleCheckpointVerificationInput,
): Promise<HandleCheckpointVerificationOutput> {
// 1. Build receipt
const receipt = CheckpointVerificationReceiptSchema.parse({
receipt_id: uuidv4(),
learn_session_id: input.learn_session_id,
ability_id: input.ability_id,
dispatch_id: input.dispatch_id,
checkpoint_id: input.checkpoint_id,
status: input.status,
evidence: input.evidence,
reason: input.reason,
agent_id: input.agent_id,
room_id: input.room_id,
created_at: new Date().toISOString(),
schema_version: 1,
});
// 2. Append receipt to JSONL (EC single-writer)
// await appendJsonl("ELNOR_MEMORY/system/learning/checkpoint_receipts.jsonl", receipt);
// 3. Emit events for downstream consumers
// if (input.status === "reached") emit("checkpoint.reached", receipt);
// if (input.status === "skipped") emit("checkpoint.skipped", receipt); // → DOC8 friction
// if (input.status === "failed") emit("checkpoint.failed", receipt); // → DOC9 repair
return { receipt_id: receipt.receipt_id, accepted: true };
}
```
### Event routing
| Status | Event emitted | Downstream consumer |
|--------|---------------|---------------------|
| `reached` | `checkpoint.reached` | DOC15 signal valuation (positive signal for checkpoint quality) |
| `skipped` | `checkpoint.skipped` | DOC8 friction analysis (was checkpoint unnecessary or did agent drift?) |
| `failed` | `checkpoint.failed` | DOC8 friction analysis + DOC9 repair proposal candidate |
### DOC4 bridge route addition
```http
POST /api/bridge/verify-checkpoint
```
Request body: `HandleCheckpointVerificationInput` (checkpoint_id, status, evidence, reason)
Response body: `HandleCheckpointVerificationOutput` (receipt_id, accepted)
Auth: same trust boundary as existing bridge tools.
### DOC11 runtime tool catalog addition
Add `verify_checkpoint` to the list of bridge tools available to the agent when a skill with non-empty `checkpoints` is active. The tool must be listed in the system prompt tool catalog alongside existing bridge tools like `elnor_learn`, `elnor_search`, etc.
**Injection rule:** When OpenClaw loads a SKILL.md whose source interpretation has a non-empty `checkpoints` array, include `verify_checkpoint` in the tool catalog for that session. When no checkpoints exist, the tool may be omitted to avoid tool-list bloat.
---
---
## §0E.11 DOC10 — Ability Availability Snapshot consumption
### Mandatory post-install saga (atomic sequence)
When a learned skill proposal transitions to `installed_private`, `approved`, or `shared_promoted`, EC must execute the following steps as a single saga with compensation:
```text
1. Materialize skill bundle (SKILL.md + manifest + metadata)
→ on failure: mark proposal "quarantined", emit learn.install.failed
2. Project manifest to OpenClaw workspace
→ on failure: revert materialization, mark proposal "quarantined"
3. Rebuild capability bridge
→ on failure: keep previous bridge, mark bridge_state "stale"
4. Refresh Ability Availability Snapshot
→ on failure: keep previous snapshot, mark snapshot_state "stale"
5. Emit events:
- learn.install.completed
- bridge.rebuild.completed
- ability.snapshot.updated
```
### Saga schema
```ts
// apps/ec-service/src/learning/install-saga.ts
export interface InstallSagaStep {
step: "materialize" | "project_to_workspace" | "rebuild_bridge" | "refresh_availability" | "emit_events";
status: "pending" | "completed" | "failed" | "compensated";
error?: string;
}
export interface InstallSagaRecord {
saga_id: string; // uuid
proposal_id: string; // uuid
ability_id: string;
install_lane: string;
steps: InstallSagaStep[];
overall_status: "in_progress" | "completed" | "failed_compensated";
started_at: string; // datetime
completed_at?: string; // datetime
}
```
### DOC10 route planner update
DOC10's intent broker / route planner must query the Ability Availability Snapshot (`ELNOR_MEMORY/system/abilities/availability_current.json`) **before** choosing a routing path. The query order is:
```text
1. Classify intent (DOC10 intent broker)
2. Resolve project/context (Core/DOC7)
3. Query Ability Availability Snapshot (GET /api/abilities/availability)
4. If matching ability found with usable_now=true:
a. Check install_lane (approved/shared preferred over experimental_private)
b. Check health_status via bridge entry
c. Route to learned skill if viable
5. If no learned skill matches or usable_now=false:
a. Fall through to connector/native/exploratory paths per existing DOC10 routing
```
### Q UI refresh contract
When `ability.snapshot.updated` fires:
| Q surface | Required refresh |
|-----------|-----------------|
| Abilities → Skills | Re-fetch skills list; newly promoted abilities appear with `source: "learned"` badge |
| Abilities → Learn → Pending Abilities | Remove the installed item from Pending; show "Promoted to Skills" receipt |
| Abilities → Learn → Active Capability Learning | Close the active session card; show completion receipt |
| Abilities → Learn → History | Append installation receipt with link to the new skill |
| Chat / Room | If the skill is relevant to active context, the agent's next turn may reference it |
**No phantom buttons rule:** If `availability_current.json` does not contain an ability, Q must NOT show it as available in Skills. If the file is stale (older than the latest `bridge.rebuild.completed` event), Q must show a "refreshing abilities..." indicator, not stale data.
---
---
## §0E.11A DOC10 — Skills catalog and no-phantom routing clarification
### Snapshot vs catalog rule
- `availability_current.json` is the routing truth used by DOC10.
- `catalog_current.json` is the richer Skills-page truth used by Q.
- DOC10 must not use the Skills catalog as a routing surrogate.
### No-phantom-buttons rule for Q refresh
After install / approval / lifecycle change, DOC10 must treat the ability as route-eligible only after:
1. the install saga completes,
2. `ability.snapshot.updated` has fired,
3. the snapshot entry shows `usable_now = true`.
If the snapshot is stale or missing, DOC10 must not claim that the learned ability is routable.
## §0E.12 DOC1 — Learning memory kinds (R11.2 comprehensive)
### Memory kinds to add
| Kind | Schema source | Description |
|---|---|---|
| `checkpoint_verification_receipt` | `CheckpointVerificationReceiptSchema` | From verify_checkpoint tool calls |
| `learning_receipt` | `LearningReceiptSchema` (R11.2 version) | Full lifecycle receipts with `ability_id`, `dispatch_id`, `summary` |
| `capability_trace` | Existing (already in R9 delta) | Execution traces |
| `skill_bundle_proposal` | Existing (already in R9 delta) | Proposal memory entries |
| `connector_receipt` | Existing (already in R9 delta) | MCP/connector receipts |
| `observed_action_event` | `ObservedActionEventSchema` (§0C.22 version) | Observation capture events |
| `category_assignment` | `CategoryAssignmentSchema` | Category membership changes |
### Indexing for new kinds
| Kind | Index by |
|---|---|
| `checkpoint_verification_receipt` | `learn_session_id`, `ability_id`, `dispatch_id`, `checkpoint_id` |
| `learning_receipt` | `learn_session_id`, `proposal_id`, `ability_id`, `event_kind` |
| `category_assignment` | `category_id`, `item_kind`, `item_id` |
| `observed_action_event` | `learn_session_id`, `adapter_kind`, `app_family` |
### Relationship index edges
| From | To | Relation |
|---|---|---|
| `checkpoint_verification_receipt:{id}` | `learn_session:{id}` | `verified_during` |
| `checkpoint_verification_receipt:{id}` | `ability:{id}` | `verified_for` |
| `learning_receipt:{id}` | `learn_session:{id}` | `receipt_for_session` |
| `learning_receipt:{id}` | `ability:{id}` | `receipt_for_ability` |
| `category_assignment:{cat_id+item_id}` | `category:{cat_id}` | `assigned_to` |
### Retention
| Kind | Retention | Compaction |
|---|---|---|
| `checkpoint_verification_receipt` | Indefinite | Nightly: aggregate counts, keep latest 100 per ability |
| `learning_receipt` | Indefinite | Nightly: compress old entries, keep summary |
| `observed_action_event` | 7 days after session terminal (§0C.16D) | Purge raw events; proposal retains derived data |
| `category_assignment` | Indefinite | None — lightweight |
---
## §0E.13 DOC8 — Checkpoint friction classes and learning mining hooks (R11.2)
### New friction classes
```ts
"checkpoint_skipped",
"checkpoint_failed",
"checkpoint_unknown_id",
"learn_session_timeout",
"learn_capture_timeout",
"proposal_build_failed",
"observation_adapter_failure",
```
### Friction event generation rules
| Trigger | Friction class | Severity |
|---|---|---|
| `checkpoint.skipped` event | `checkpoint_skipped` | low |
| `checkpoint.failed` event | `checkpoint_failed` | medium |
| `checkpoint.failed` with no subsequent checkpoint.reached | `checkpoint_failed` | high |
| verify_checkpoint with unknown ID | `checkpoint_unknown_id` | low |
| Session auto-cancelled by TTL | `learn_session_timeout` | medium |
| Capture auto-paused by TTL | `learn_capture_timeout` | low |
| Proposal generation failed | `proposal_build_failed` | medium |
| Observation adapter went unhealthy during capture | `observation_adapter_failure` | medium |
### Skill mining interaction
- Skills with >80% checkpoint-reached rate → strong promotion candidates
- Skills with inconsistent checkpoint patterns → high variation score, do not auto-promote
- Skills where specific checkpoints always fail → checkpoint/SKILL.md needs revision, not entire skill
### Nightly aggregation
Nightly job Phase 4/5 should aggregate per ability:
- `checkpoint_id` → reached/skipped/failed counts (rolling 30 days)
- Feed DOC15 signal valuation and DOC9 repair candidate scoring
---
## §0E.14 DOC9 — Checkpoint failure and learning repair paths (R11.2)
### New repair issue classes
Add to `SkillRepairProposalSchema.issue_class` enum:
```ts
"checkpoint_failure",
"generation_quality", // SKILL.md contains rigid sequences or ephemeral selectors
```
### Repair trigger thresholds
| Condition | Action |
|---|---|
| ≥3 `checkpoint.failed` on same `checkpoint_id` across ≥2 executions | Repair proposal targeting that checkpoint |
| ≥5 `checkpoint.skipped` on same `checkpoint_id` with no later reached | Repair proposal — checkpoint may be unreachable |
| `checkpoint.failed` + reason contains "timeout"/"element not found" + lint would fail CKP-001–003 | Repair proposal with dual issue: `checkpoint_failure` + `lint` |
| Proposal build repeatedly fails for same app family | Repair proposal targeting observation/generation pipeline |
### New optional fields on SkillRepairProposalSchema
```ts
failing_checkpoint_id: z.string().max(80).optional(),
failure_evidence: z.array(z.string().max(400)).default([]),
```
### Rollback path
If a privately installed learned skill causes repeated checkpoint failures:
1. DOC9 generates repair proposal
2. If repair not feasible, DOC9 may propose quarantine
3. Quarantined ability is removed from availability snapshot
4. User sees quarantine notice in Q with "Repair" / "Delete" / "Unquarantine" actions
---
## §0E.15 DOC15 — Checkpoint verification and learning quality signals (R11.2)
### New signal kinds
```ts
"checkpoint_positive",
"checkpoint_neutral_or_negative",
"checkpoint_negative",
"checkpoint_sequence_complete",
"checkpoint_no_telemetry",
"interpretation_no_checkpoints",
"generation_quality_good", // SKILL.md passes lint and produces checkpoints
"generation_quality_poor", // SKILL.md contains rigid sequences
"later_use_success", // Learned ability was invoked and succeeded
"later_use_failure", // Learned ability was invoked and failed
```
### Correlation rules
| Checkpoint pattern | Execution outcome | DOC15 interpretation |
|---|---|---|
| All reached | Success | Strong positive for skill + all checkpoints |
| Some skipped, none failed | Success | Positive for skill; skipped checkpoints may be unnecessary |
| Some failed | Success | Positive for skill; negative for failed checkpoints |
| All reached | Failure | Negative for skill; neutral for checkpoints |
| Some failed | Failure | Negative for both skill and failed checkpoints |
### Interpretation quality scoring
- Interpretations whose checkpoints correlate with success → higher usefulness
- Interpretations whose checkpoints are consistently skipped → flag for revision
- Interpretations with zero checkpoints → no checkpoint signal; use other signals
- SKILL.md that passes CKP lint → `generation_quality_good`
- SKILL.md that fails CKP lint → `generation_quality_poor`
---
## §0E.16 DOC12 — Room-scoped learning visibility (R11.2)
### Room transcript event types to add
```text
checkpoint.reached
checkpoint.skipped
checkpoint.failed
learn.session.started
learn.session.cancelled
learn.capture.started
learn.capture.stopped
learn.proposal.created
learn.install.completed
ability.activated
ability.deactivated
```
### Wiring
When any of these events occur during a room-scoped dispatch/session (receipt has non-null `room_id`):
1. Include event in room transcript timeline
2. Show status in room participant activity feed
3. Allow room-level filtering of learning/checkpoint events
---
## §0E.17 ELNOR First-Wave MCP Pack — M365 auth policy enforcement (R11.2)
| Doc | Obligation |
|-----|-----------|
| DOC4 | Bridge routes for MCP registry must reject M365 connector registration with `auth_mode: "api_key"` or `auth_mode: "none"`. Return error: `"M365 connectors require oauth2_on_behalf_of or oauth2_delegated auth mode."` |
| DOC11 | Runtime health checks for M365 servers must verify auth profile uses `oauth2_on_behalf_of` or `oauth2_delegated`. Static key detected → mark `degraded` with reason `"forbidden_auth_mode_for_m365"`. |
| Q UI | Connector settings must not offer `api_key` as auth mode for M365 connectors. |
---
## §0E.18 DOC4 — Bridge route additions (R11.2)
### New routes DOC4 must register
```http
POST /api/bridge/verify-checkpoint # Checkpoint verification tool
POST /api/config/intents # Configuration intent submission
```
### verify_checkpoint contract
Request: `{ checkpoint_id, status, evidence, reason? }`
Response: `{ receipt_id, accepted }`
Auth: same trust boundary as existing bridge tools.
### config/intents contract
Request: `ConfigurationIntentSchema` from `packages/contracts/src/common/configuration-intent.ts`
Response: `{ intent_id, accepted, applied_at? }`
Auth: same trust boundary. Fail-closed: if EC rejects, the wrapper's requested config change does NOT take effect.
### Deprecated route migration
DOC4 must implement `308 Permanent Redirect` semantics or an internal canonical alias preserving method and body for deprecated `/teach/*` and `/skills/mining/*` routes per DOC3 §0C.20B.
---
## §0E.19 DOC11 — Learning runtime truth additions (R11.2)
DOC11 must provide the following runtime truth fields for the learning subsystem:
### Tool catalog injection
When a skill with non-empty `checkpoints` is active:
- Include `verify_checkpoint` in the agent's tool catalog
- Set `verify_checkpoint_available: true` in runtime truth
When no checkpoints exist: omit the tool.
### Observation adapter health
DOC11 must report health status for each observation adapter that depends on runtime state:
| Adapter | DOC11 runtime check |
|---|---|
| `browser_dom`, `browser_snapshot` | Managed browser running and CDP connected |
| `wrapper_receipt` | Bridge connection healthy |
| `mcp_receipt` | At least one MCP server healthy |
| `terminal_command`, `process_launch` | Shell access available |
| Phase 2+ adapters | Report `not_available` until implemented |
### Install-lane loadability
DOC11 must confirm that a privately installed skill is actually loadable by OpenClaw:
- SKILL.md exists at projected path
- Capability manifest exists at projected path
- No file-system permission errors
- No tool-name collisions with native tools
If any check fails, DOC11 reports `usable_now: false` with reason.
---
## §0E.20 DOC10 — Ability-aware routing (R11.2)
### Snapshot consumption
DOC10's route planner must query the Ability Availability Snapshot (`ELNOR_MEMORY/system/abilities/availability_current.json`) before choosing a routing path:
1. Classify intent (DOC10 intent broker)
2. Resolve project/context (Core/DOC7)
3. Query `POST /api/abilities/lookup` with user query + project context
4. If match found with `score >= 0.3` and `usable_now = true`:
- Check install_lane (shared > approved > experimental)
- Check checkpoint_health (strong/moderate preferred)
- Route to learned skill if viable
5. If no match or `usable_now = false`:
- Fall through to connector/native/exploratory paths
### Checkpoint-aware routing scores
| Signal | Routing impact |
|---|---|
| checkpoint_health = "strong" (>80% reached rate) | Boost routing score |
| checkpoint_health = "weak" (<50% reached or >30% failed) | Demote routing score |
| checkpoint_health = "no_data" | Neutral |
| Ability quarantined | Do not route |
### DOC10 awareness snapshot addition
Add `checkpoint_health` field to DOC10's `CapabilityAwarenessSnapshot`:
```ts
checkpoint_health: z.enum([
"strong", "moderate", "weak", "no_data", "quarantined"
]).optional(),
```
This field is derived during availability snapshot refresh and does not require a separate runtime query.
---
## §0E.21 Q UI — Required surfaces for DOC3 R11.2 (comprehensive)
### Pages and views
| Surface | Location | Data source |
|---|---|---|
| Ability Learning page | Abilities → Learn | Learn routes §0C.16 |
| Learn New Ability cards | Within Ability Learning | `CreateLearnSessionRequestSchema` |
| Active Capability Learning | Tab within Learn | `GET /api/learn/sessions` filtered by non-terminal |
| Pending Abilities | Tab within Learn | `GET /api/learn/proposals` + `PendingAbilityUiStateSchema` |
| History | Tab within Learn | `GET /api/learn/history` |
| LearnSession detail drawer | Opened from Active/History | `GET /api/learn/sessions/:id/detail` |
| LearnSession overlay | Global overlay during capture | SSE `GET /api/learn/sessions/:id/events` |
| Proposal review drawer | Opened from Pending | `GET /api/learn/proposals/:id/detail` |
| Checkpoint progress view | Within session/dispatch detail | Checkpoint receipts routes |
| Observation mode banner | Global persistent banner | `GET /api/learn/sessions/:id/observation-scope` |
| Ability availability panel | Within Skills page | `GET /api/abilities/availability` |
| Install saga progress | Within Pending → installing item | Real-time saga status |
| Category assignment menu | Right-click context menu | `POST /api/categories/:id/assign` |
| Category browser | Left-nav browser section | `GET /api/categories` |
### Proposal review drawer wireframe (lint passing)
```
┌─────────────────────────────────────────┐
│ Proposal: Export PDF from Westlaw │
│ Status: Ready for Review │
│ │
│ ┌─── Checkpoints ──────────────────────┐ │
│ │ 1. Search results loaded ✓ lint │ │
│ │ 2. Target case opened ✓ lint │ │
│ │ 3. Export dialog visible ✓ lint │ │
│ │ 4. PDF format selected ✓ lint │ │
│ │ 5. Export confirmed ✓ lint │ │
│ │ │ │
│ │ Lint: ✓ Passed (0 errors) │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌─── Generated SKILL.md ──────────────┐ │
│ │ (preview of checkpoint-oriented │ │
│ │ natural-language instructions) │ │
│ └──────────────────────────────────────┘ │
│ │
│ [Approve] [Install Private] [Revise] │
│ [Reject] [Request More Tests] │
└─────────────────────────────────────────┘
```
### Proposal review drawer wireframe (lint failing)
```
┌─────────────────────────────────────────┐
│ Proposal: Click Export Button │
│ Status: Lint Failed │
│ │
│ ┌─── Checkpoints ──────────────────────┐ │
│ │ 1. Click div-8472 ✗ CKP-001│ │
│ │ ⚠ Contains raw DOM selector │ │
│ │ 2. Wait for react-uid-4f2a ✗ CKP-003│ │
│ │ ⚠ Contains ephemeral ID │ │
│ │ │ │
│ │ Lint: ✗ Failed (2 errors) │ │
│ │ Cannot approve until lint passes. │ │
│ └──────────────────────────────────────┘ │
│ │
│ [Revise] [Reject] │
│ (Approve / Install disabled) │
└─────────────────────────────────────────┘
```
### Required UI states per surface
| Surface | States |
|---|---|
| Learn New Ability | loading, ready, session_already_active |
| Active Capability Learning | loading, empty, has_sessions |
| Pending Abilities | loading, empty, has_items |
| History | loading, empty, has_items |
| LearnSession detail | loading, armed, capturing, paused, stopped, reviewing, awaiting_questions, drafting, testing, ready_for_review, installing, installed, approved, rejected, cancelled, quarantined, partial_deployment |
| Observation banner | hidden, active, degraded (adapter issue), stopping |
| Proposal review | loading, lint_passing, lint_failing, testing, ready, approved, rejected |
| Checkpoint progress | no_checkpoints, in_progress, complete, partial_failure |
| Category menu | loading, ready, no_categories |
---
## §0E.22 DOC2 — Learning artifact freshness
When a learned skill depends on connector data or support packs that have freshness constraints:
- If the underlying connector fact has `freshness_kind: "cached"` and `cached_as_of` is older than the configured staleness threshold, the ability availability snapshot should mark the ability with `reason_unusable: "dependency_stale"`.
- DOC2 freshness checks should include learned abilities as consumers of connector freshness, not just direct queries.
---
## §0E.23 DOC13 — Cost tracking for learning and validation
DOC13 must track:
- LLM tokens used during `compute-semantic-interpretation` (proposal generation)
- LLM tokens used during `run-validation` (validation runs)
- LLM tokens used during `verify_checkpoint` evidence evaluation (if LLM-assisted)
- Connector/MCP calls during validation rehearsal (may incur API costs)
These costs should be attributed to the `learn_session_id` and visible in the session detail and proposal review drawer.
---
## §0E.24 Companion-doc amendment priority tiers (authoritative)
### Tier 1 — Hard blockers (must complete before Learn ships)
| Doc | Amendment |
|---|---|
| DOC4 | Register `verify_checkpoint` and `config/intents` bridge routes |
| DOC11 | Report observation adapter health + install-lane loadability |
| Q UI | Implement Learn page, session overlay, proposal drawer (from §0E.21) |
### Tier 2 — Required for later-use (must complete before "learned skills auto-route")
| Doc | Amendment |
|---|---|
| DOC10 | Consume ability availability snapshot + lookup contract |
| DOC10 | Add checkpoint_health to awareness snapshot |
| DOC1 | Add checkpoint and learning receipt memory kinds |
### Tier 3 — Required for learning quality (should complete within 30 days of launch)
| Doc | Amendment |
|---|---|
| DOC8 | Add checkpoint friction classes + mining hooks |
| DOC9 | Add checkpoint failure repair path |
| DOC15 | Add checkpoint signal valuation + interpretation quality scoring |
| DOC12 | Add room-scoped learning events |
| DOC13 | Add learning cost tracking |
| DOC2 | Add learning artifact freshness checks |
### Tier 4 — Future hardening
| Doc | Amendment |
|---|---|
| DOC10 | Adopt shared WorkflowGraph for tasks if Core chooses |
| DOC18 | Resolve LlamaIndex persistence policy (ephemeral vs managed) |
| Core | Define TaskTemplate/TaskInstance/AutomationDefinition if DOC3 shared-IR is adopted |
---
## §0E.25 Exact owner-doc obligations added by this revision (authoritative)
### DOC4 obligations
DOC4 must add bridge/runtime ownership text covering:
- registration of the public MCP management routes listed above,
- durable handling of `oauth_state_ref` and `pkce_verifier_ref`,
- internal dispatch consumption of `M365OperationRequestSchema`,
- pause/resume behavior for ask-first,
- Acrobat route dispatch and receipt emission,
- staged upload/temp-artifact storage and cleanup behavior,
- learn read/list/detail/event route registration,
- and category route registration.
### DOC10 obligations
DOC10 must add route-planner / orchestration text that:
- consumes the Skills catalog / availability snapshot already required by earlier DOC3 work,
- consumes `MCPServerListResponseSchema` for connector badge truth,
- never plans routes to the removed custom ELNOR wrappers,
- treats `approval_required`, `auth_required`, and `degraded` as planner-visible truth states,
- consumes the learn read/list/detail routes as the planner-visible read-model family for Learn surfaces,
- and uses the composed connector view rather than registry-only health fields.
### DOC11 obligations
DOC11 must add runtime-truth fields for:
- connector composed-list generation time,
- pending auth challenges count,
- pending ask-first approvals count,
- Acrobat adapter state,
- Acrobat supported capabilities,
- whether a connector is interactive vs background-only,
- and any optional push channel for connector health only if DOC11 later formalizes it beyond DOC3’s poll-first rule.
### Q UI obligations
Q docs must add or revise:
- connector/server card rendering based on `MCPServerListResponseSchema`,
- connector auth handling bound only to the normalized named MCP request/response schemas,
- ask-first approval queue and detail drawer,
- import upload/list/detail/retry/discard states,
- trigger-test drawer states,
- skill-pack read surface states,
- learn sessions/proposals/history/receipts/detail/event read surfaces,
- category CRUD + assignment surfaces, including `CATEGORY_LIMIT_REACHED`,
- stale stop-capture handling for `CAPTURE_ALREADY_STOPPED`,
- Acrobat action states and degraded handling,
- and control-backing rows for every required DOC3-owned control.
### DOC10 ledger / integration-ledger obligations
The suite-wide ledger must add verification rows for:
- custom-wrapper removal
- Acrobat active-scope completeness
- MCP composed-list / badge truth
- ask-first pause/resume
- shared-auth delete safety
- staged upload / import retry idempotency
- trigger-test + packs routes in active scope
- learn read/list/detail/event family in active scope
- and category-route normalization
## 8.x Required control-backing inventory (authoritative — exhaustive)
Every DOC3-owned **action control** must appear in this table. If a control is absent, it is not a required shipped action control. No row may use an ad hoc unnamed response shape where DOC3 now defines a named schema.
| Control | UI location | Route / command | Request schema | Success response | Error / degraded states required in UI | Durable side effect | Read-model refresh | Modal / confirm text |
|---|---|---|---|---|---|---|---|---|
| Start Learn session | Learn → card action | `POST /api/learn/sessions` | `CreateLearnSessionRequestSchema` | `CreateLearnSessionResponseSchema` | `LEARN_SESSION_ALREADY_ACTIVE`, `PARTIAL_DEPLOYMENT`, `OBSERVATION_UNAVAILABLE`, generic error | EC appends session + current views | refresh active learn views; subscribe SSE if started | none |
| Start capture | LearnSession detail / overlay | `POST /api/learn/sessions/:sessionId/start` | route params + no body | `StartSessionResponseSchema` | route unavailable, adapter unavailable, stale session, generic error | EC appends lifecycle event and arms configured observation runtime | refresh detail + active list + observation scope + SSE | none |
| Pause capture | LearnSession detail / overlay | `POST /api/learn/sessions/:sessionId/pause` | route params + no body | `SessionActionResponseSchema` | route unavailable, stale session, generic error | EC appends lifecycle event | refresh detail + active list + SSE | none |
| Resume capture | LearnSession detail / overlay | `POST /api/learn/sessions/:sessionId/resume` | route params + no body | `SessionActionResponseSchema` | route unavailable, stale session, adapter unavailable, generic error | EC appends lifecycle event | refresh detail + active list + SSE | none |
| Stop capture | LearnSession detail / overlay | `POST /api/learn/sessions/:sessionId/stop` | route params + no body | `StopSessionResponseSchema` | `CAPTURE_ALREADY_STOPPED`, blocked if not capturing/paused, generic error | EC appends lifecycle event and closes active capture | refresh detail + active/history + SSE + observation scope | `Stop capture and move to review?` |
| Cancel Learn session | LearnSession detail / overlay | `POST /api/learn/sessions/:sessionId/cancel` | route params + no body | `SessionActionResponseSchema` | blocked if install already running; generic error | EC appends lifecycle event and marks session cancelled | refresh detail + active/history + SSE | `Cancel this learning session?` |
| Mark goal | LearnSession detail / capture rail | `POST /api/learn/sessions/:sessionId/mark-goal` | `MarkGoalRequestSchema` | `SessionActionResponseSchema` | blocked outside capture state, invalid marker payload, generic error | EC appends goal marker event | refresh timeline + detail + SSE | none |
| Mark step | LearnSession detail / capture rail | `POST /api/learn/sessions/:sessionId/mark-step` | `MarkStepRequestSchema` | `SessionActionResponseSchema` | blocked outside capture state, invalid marker payload, generic error | EC appends step marker event | refresh timeline + detail + SSE | none |
| Trim session | LearnSession detail / capture rail | `POST /api/learn/sessions/:sessionId/trim` | `TrimRequestSchema` | `SessionActionResponseSchema` | invalid boundary, stale session, generic error | EC appends trim event and updates session boundaries | refresh timeline + detail + SSE | `Apply this trim to the captured session?` |
| Answer questions | Proposal review / question pane | `POST /api/learn/sessions/:sessionId/answer-questions` | `AnswerQuestionsRequestSchema` | `AnswerQuestionsResponseSchema` | missing question id, stale proposal, generic error | EC appends answer event and updates question state | refresh proposal detail / session detail | none |
| Set rehearsal policy | LearnSession detail / test-policy panel | `POST /api/learn/sessions/:sessionId/set-test-policy` | `SetTestPolicyRequestSchema` | `SessionActionResponseSchema` | invalid policy, stale session, generic error | EC updates session test policy and appends lifecycle note | refresh session detail + proposal detail | none |
| Generate proposal | LearnSession detail | `POST /api/learn/sessions/:sessionId/generate-proposal` | route params + no body | `GenerateProposalResponseSchema` | blocked if session not reviewable; missing interpretation; generic error | EC creates proposal + lifecycle events | refresh pending abilities + session detail | `Generate proposal now?` |
| Start validation run | Proposal review drawer | `POST /api/learn/proposals/:proposalId/validate` | `StartValidationRunRequestSchema` | `ValidationRunResponseSchema` | blocked if proposal incomplete; checkpoint lint fail; generic error | EC appends validation run + receipt | refresh proposal detail / validation list | `Run validation now?` |
| Abort validation run | Proposal review drawer | `POST /api/learn/proposals/:proposalId/validation-runs/:runId/abort` | route params + no body | `ValidationRunResponseSchema` | no active run; generic error | EC appends lifecycle event and marks run aborted | refresh validation list / proposal detail | `Abort running validation?` |
| Revise proposal | Proposal review drawer | `POST /api/learn/proposals/:proposalId/revise` | `ProposalReviseRequestSchema` | `ProposalDetailResponseSchema` | stale proposal, blocked state, generic error | EC appends revision request event and returns proposal to drafting | refresh proposal detail / pending list | `Send this proposal back for revision?` |
| Request more tests | Proposal review drawer shortcut | `POST /api/learn/proposals/:proposalId/revise` | `ProposalReviseRequestSchema` with UI-seeded `revision_instructions` requesting more tests/evidence | `ProposalDetailResponseSchema` | stale proposal, blocked state, generic error | EC appends revision request event and returns proposal to drafting | refresh proposal detail / pending list | `Request more testing before approval?` |
| Install privately | Proposal review drawer | `POST /api/learn/proposals/:proposalId/install` | `ProposalInstallRequestSchema` with `install_lane = "experimental_private"` | `ProposalInstallResponseSchema` | checkpoint failure, bridge failure, availability refresh failure, partial deployment | EC appends install saga + ability artifacts | refresh pending / catalog / availability / receipts | `Install as private ability?` |
| Approve shared/workspace | Proposal review drawer | `POST /api/learn/proposals/:proposalId/approve` | `ApproveProposalRequestSchema` | `ProposalMutationResponseSchema` | blocked if review incomplete; generic error | EC appends lifecycle event + install lane change | refresh pending / catalog / availability | `Approve for workspace use?` |
| Reject proposal | Proposal review drawer | `POST /api/learn/proposals/:proposalId/reject` | `RejectProposalRequestSchema` | `ProposalMutationResponseSchema` | stale proposal; generic error | EC appends lifecycle event | refresh pending / history | `Reject this proposal?` |
| Upload skill bundle | Skills → Import bundle | `POST /api/skills/import/uploads` | multipart file `bundle` + `SkillImportUploadMetadataSchema` | `SkillImportUploadResponseSchema` | `SKILL_IMPORT_FILE_TOO_LARGE`, `SKILL_IMPORT_UNSUPPORTED_MIME`, `SKILL_IMPORT_UNSUPPORTED_EXTENSION`, generic error | EC writes temp upload metadata | refresh upload state only | none |
| Delete uploaded temp bundle | Skills → Import wizard | `DELETE /api/skills/import/uploads/:tempArtifactRef` | route params only | `SkillImportDeleteUploadResponseSchema` | already-bound-to-stage, not found, generic error | EC deletes temp artifact | refresh upload state | `Delete uploaded bundle before staging?` |
| Scan uploaded skill bundle | Skills → Import wizard | `POST /api/skills/import/scan` | `SkillImportScanRequestSchema` | `SkillImportScanResponseSchema` | expired upload, invalid archive, compatibility failure | EC appends import record + compatibility report | refresh import wizard / import list / import detail | none |
| Stage scanned bundle | Skills → Import wizard | `POST /api/skills/import/stage` | `SkillImportStageRequestSchema` | `SkillImportStageResponseSchema` | expired upload, blocked by policy, generic error | EC mutates import record | refresh import list / detail | `Stage this bundle for review?` |
| Approve imported bundle | Skills → Import wizard | `POST /api/skills/import/approve` | `SkillImportApproveRequestSchema` | `SkillImportTerminalActionResponseSchema` | blocked by compatibility/policy, generic error | EC marks import approved and emits receipt | refresh import detail / list / catalog if applicable | `Approve imported bundle?` |
| Reject imported bundle | Skills → Import wizard | `POST /api/skills/import/reject` | `SkillImportRejectRequestSchema` | `SkillImportTerminalActionResponseSchema` | reason required, generic error | EC marks import rejected | refresh import detail / list | `Reject imported bundle?` |
| Install imported bundle privately | Skills → Import wizard | `POST /api/skills/import/install-private` | `SkillImportInstallPrivateRequestSchema` | `SkillImportTerminalActionResponseSchema` | blocked by loadability, generic error | EC queues import install and returns `saga_id` when async install begins | refresh import detail / list / catalog | `Install imported bundle privately?` |
| Discard imported bundle | Skills → Import wizard | `POST /api/skills/import/discard` | `SkillImportDiscardRequestSchema` | `SkillImportTerminalActionResponseSchema` | terminal-state block, generic error | EC marks import discarded | refresh import detail / list | `Discard this import record?` |
| Retry import step | Skills → Import wizard | `POST /api/skills/import/retry` | `SkillImportRetryRequestSchema` | `SkillImportTerminalActionResponseSchema` | `retry_limit_reached`, generic error | EC re-queues scan/stage/install | refresh import detail / list | `Retry failed import step?` |
| Run trigger test | Skills → Trigger-test drawer | `POST /api/skills/trigger-test` | `SkillTriggerTestRequestSchema` | `SkillTriggerTestResponseSchema` | missing trigger text, missing target, generic error | EC appends trigger-test receipt only | refresh trigger-test panel | none |
| Create category | Category browser / create modal | `POST /api/categories` | `{ title: string, color?: string, schema_version: 1 }` | `{ category: CategorySchema, schema_version: 1 }` | `CATEGORY_LIMIT_REACHED`, duplicate title, invalid color, generic error | EC appends category create event | refresh category browser / category drawer | `Create this category?` |
| Update category | Category browser / edit modal | `PUT /api/categories/:categoryId` | `{ title?: string, color?: string, schema_version: 1 }` | `{ category: CategorySchema, schema_version: 1 }` | `CATEGORY_LIMIT_REACHED`, not found, invalid color, generic error | EC appends category update event | refresh category browser / category drawer | `Save category changes?` |
| Delete category | Category browser / delete modal | `DELETE /api/categories/:categoryId` | route params only | `{ deleted: true, deleted_assignments: number, schema_version: 1 }` | not found, protected category, generic error | EC appends category delete event and removes assignments | refresh category browser / affected chips | `Delete this category and its assignments?` |
| Assign category | Skills / Learn side panel | `POST /api/categories/:categoryId/assign` | `{ item_kind: CategoryItemKindSchema, item_id: string, schema_version: 1 }` | `CategoryAssignmentSchema` | duplicate assignment, stale category, generic error | EC appends category assignment event | refresh category chips / category drawer | none |
| Remove category assignment | Category drawer / detail sheet | `DELETE /api/categories/:categoryId/items/:itemKind/:itemId` | route params only | `CategoryDeleteAssignmentResponseSchema` | not assigned, stale category, generic error | EC writes category change event | refresh category drawer / detail sheet | `Remove item from this category?` |
| Favorite toggle | Skills / Learn side panel | `POST /api/categories/:favoritesCategoryId/assign` or `DELETE /api/categories/:favoritesCategoryId/items/:itemKind/:itemId` | same category assign/delete request shapes using reserved favorites category | `CategoryAssignmentSchema` or `CategoryDeleteAssignmentResponseSchema` | protected favorites category missing, generic error | EC writes favorite assignment/unassignment event | refresh favorite icon + chips | none |
| Add connector server | Connector settings | `POST /api/mcp/servers/register` | `MCPServerCreateRequestSchema` | `MCPServerMutationResponseSchema` | form errors, unsupported auth mode, generic error | EC appends registry write + receipt | refresh connector list + receipt list | `Register this connector?` |
| Edit connector server | Connector card drawer | `PATCH /api/mcp/servers/:serverId` | `MCPServerPatchRequestSchema` | `MCPServerMutationResponseSchema` | form errors, unsupported mutation, generic error | EC appends registry patch + receipt | refresh connector list + receipt list | `Save connector changes?` |
| Delete connector server | Connector card drawer | `DELETE /api/mcp/servers/:serverId` | route params only | `MCPServerDeleteResponseSchema` | blocked by policy, generic error | EC appends delete receipt; may retain shared auth profile | refresh connector list + receipt list + auth-profile list | `Delete this connector server?` |
| Create auth profile | Connector settings / auth-profile manager | `POST /api/mcp/auth-profiles` | `MCPAuthProfileCreateRequestSchema` | `MCPAuthProfileSchema` | form errors, forbidden auth mode, generic error | EC writes auth-profile record | refresh auth-profile list + connector drawers | `Create this auth profile?` |
| Edit auth profile | Connector settings / auth-profile manager | `PATCH /api/mcp/auth-profiles/:authProfileId` | `MCPAuthProfilePatchRequestSchema` | `MCPAuthProfileSchema` | form errors, forbidden auth mode, generic error | EC patches auth-profile record | refresh auth-profile list + connector drawers | `Save auth profile changes?` |
| Delete auth profile | Connector settings / auth-profile manager | `DELETE /api/mcp/auth-profiles/:authProfileId` | route params only | `MCPAuthProfileDeleteResponseSchema` | `MCP_AUTH_PROFILE_IN_USE`, generic error | EC deletes or retains auth-profile per policy | refresh auth-profile list + connector drawers | `Delete this auth profile?` |
| Start connector auth | Connector card | `POST /api/mcp/servers/:serverId/auth/start` | `MCPAuthStartRequestSchema` | `MCPAuthStartResponseSchema` | auth-start error, generic error | EC appends auth-start receipt | refresh auth status + receipt list | none |
| Respond to auth challenge | Connector challenge modal | `POST /api/mcp/auth/challenge/respond` | `MCPAuthChallengeRespondRequestSchema` | `MCPAuthChallengeRespondResponseSchema` | stale challenge, denied, expired, generic error | EC appends auth-challenge receipt | refresh auth status / server health / receipt list | buttons: `Approve`, `Deny`, `Retry` |
| Refresh connector auth | Connector card | `POST /api/mcp/servers/:serverId/auth/refresh` | `MCPAuthRefreshRequestSchema` | `MCPServerAuthStatusSchema` | auth expired, refresh denied, generic error | EC appends auth-refresh receipt | refresh auth status + receipt list | none |
| Revoke connector auth | Connector card | `POST /api/mcp/servers/:serverId/auth/revoke` | `MCPAuthRevokeRequestSchema` | `MCPAuthRevokeResponseSchema` | revoke denied, generic error | EC appends auth-revoke receipt | refresh auth status + receipt list | `Revoke connector authorization?` |
| Update connector policy | Connector card / policy drawer | `POST /api/mcp/policy/update` | `{ target: MCPPolicyTargetSchema, decision: MCPPolicyDecisionSchema, schema_version: 1 }` | `MCPEffectivePolicySchema` | invalid target, generic error | EC writes effective-policy update | refresh connector list + policy drawer + receipt list | `Apply this policy change?` |
| Run connector smoke test | Connector card | `POST /api/mcp/servers/:serverId/smoke-test` | `MCPSmokeTestRequestSchema` | `MCPSmokeTestResponseSchema` | connector blocked, auth expired, rate limited, generic error | EC appends smoke-test receipt only | refresh server health + receipt list | `Run connector smoke test?` |
| Approve ask-first dispatch | Pending approvals drawer | `POST /api/mcp/ask-first/:dispatchId/approve` | `MCPAskFirstDecisionRequestSchema` with `decision != "deny"` | `MCPAskFirstDecisionResponseSchema` | stale dispatch, expired, generic error | EC updates paused dispatch, preserves `correlation_id`, emits receipt | refresh approvals + receipts + affected surface | `Approve this connector action?` |
| Deny ask-first dispatch | Pending approvals drawer | `POST /api/mcp/ask-first/:dispatchId/deny` | `MCPAskFirstDecisionRequestSchema` with `decision = "deny"` | `MCPAskFirstDecisionResponseSchema` | stale dispatch, expired, generic error | EC updates paused dispatch, preserves `correlation_id`, emits receipt | refresh approvals + receipts + affected surface | `Deny this connector action?` |
| Acrobat extract text | PDF tools / document drawer | `POST /api/adapters/acrobat/extract-text` | `AcrobatExtractTextRequestSchema` | `AcrobatOperationResponseSchema` | `ACROBAT_UNAVAILABLE`, `ACROBAT_SOURCE_NOT_FOUND`, generic error | EC appends Acrobat operation receipt and output ref | refresh document tools state + receipt list | none |
| Acrobat extract tables | PDF tools / document drawer | `POST /api/adapters/acrobat/extract-tables` | `AcrobatExtractTablesRequestSchema` | `AcrobatOperationResponseSchema` | `ACROBAT_UNAVAILABLE`, `ACROBAT_SOURCE_NOT_FOUND`, generic error | EC appends Acrobat operation receipt and output ref | refresh document tools state + receipt list | none |
| Acrobat OCR | PDF tools / document drawer | `POST /api/adapters/acrobat/ocr` | `AcrobatOCRRequestSchema` | `AcrobatOperationResponseSchema` | `ACROBAT_UNAVAILABLE`, `ACROBAT_OCR_UNSUPPORTED`, generic error | EC appends Acrobat operation receipt and output ref | refresh document tools state + receipt list | none |
| Acrobat redaction prep | PDF tools / document drawer | `POST /api/adapters/acrobat/redaction-prep` | `AcrobatRedactionPrepRequestSchema` | `AcrobatOperationResponseSchema` | `ACROBAT_REDACTION_PREP_REQUIRES_APPROVAL`, `ACROBAT_UNAVAILABLE`, generic error | EC appends Acrobat operation receipt and output ref | refresh document tools state + receipt list | `Prepare redaction candidates for this file?` |
#### Mandatory state-envelope rule
Every required DOC3-owned action control must have:
- loading state,
- success state,
- blocked/degraded state,
- error state,
- destructive-confirm state where applicable,
- explicit success response handling,
- and explicit durable side-effect language.
No required control may rely on “button disappears” as its only state handling.
#### Explicit omissions rule
The following are **not** required shipped controls unless a future redline adds route-backed rows for them:
- standalone ability activate/deactivate/quarantine/unquarantine buttons in Q,
- standalone `Request adapter` buttons,
- any second observation runtime toggle separate from create-session observation mode,
- inherited skill-drawer `edit`, `duplicate`, `disable`, or `delete` actions.
## 8.xA Required read-surface backing matrix (authoritative)
Every DOC3-owned **read surface** must appear in this table. If a read surface is absent, it is not a required shipped surface.
| Surface | Primary route(s) | Required empty / degraded / blocked states | Refresh triggers | Notes |
|---|---|---|---|---|
| Learn → Active sessions tab | `GET /api/learn/sessions` | empty active list; partial deployment blocked; generic load error | session start/stop/cancel; manual refresh; app load | must use plural route family only |
| LearnSession detail drawer | `GET /api/learn/sessions/:sessionId/detail` | session missing; stale session; generic load error | on open; after any session mutation | source of truth for detail badges |
| LearnSession event overlay | `GET /api/learn/sessions/:sessionId/events` | SSE disconnected banner; terminal-session closure; generic stream error | auto-subscribe on open/start; unsubscribe on terminal | no hidden background stream assumption |
| Observation scope banner | `GET /api/learn/sessions/:sessionId/observation-scope` | no active observer; stale session; generic load error | session open; start/pause/resume/stop | banner text must match backend mode |
| Checkpoint receipts panel | `GET /api/learn/sessions/:sessionId/checkpoint-receipts` | empty receipt list; generic load error | after checkpoint verification; on open | no guessed receipt summaries |
| Learn → Pending proposals tab | `GET /api/learn/proposals` | empty proposals list; generic load error | proposal generation; approve/reject/install/revise | must not depend on appendix-only routes |
| Proposal detail drawer | `GET /api/learn/proposals/:proposalId/detail` | missing proposal; stale proposal; generic load error | on open; after proposal mutations | questions, answers, dependencies, validation status live here |
| Validation runs panel | `GET /api/learn/proposals/:proposalId/validation-runs` | empty runs; generic load error | validation start/abort; on open | tied to proposal detail |
| Learn → History tab | `GET /api/learn/history` | empty history; generic load error | session terminal transitions; manual refresh | terminal sessions only |
| Learn → Receipts tab | `GET /api/learn/receipts` | empty receipts; generic load error | any learning receipt emission; manual refresh | no local synthesis |
| Skills → Import list | `GET /api/skills/import/list` | empty imports; generic load error | upload/scan/stage/install/reject/discard/retry | source of truth for import rows |
| Skills → Import detail | `GET /api/skills/import/:importId` | missing import; generic load error | list row open; any import mutation | includes compatibility report and warnings |
| Skills → Trigger-test drawer | `POST /api/skills/trigger-test` + local drawer state | empty pre-run state; generic run error | on each submit | results must use `SkillTriggerTestResponseSchema` only |
| Skills → Packs surface | `GET /api/skills/packs` | empty packs; deferred pack warning only if backend says none; generic load error | on open; manual refresh | no inferred pack list |
| Categories browser | category list/current view + CRUD routes | empty categories; `CATEGORY_LIMIT_REACHED`; generic load error | create/update/delete/assign/remove | limit errors must be explicit, not silent |
| Connector cards | `GET /api/mcp/servers` | empty connector list; auth_required; approval_required; degraded; disabled | app load; manual refresh; after any connector mutation | badge truth from backend only |
| Connector auth drawer | `GET /api/mcp/servers/:serverId/auth/status` | auth missing; challenge required; generic load error | after start/refresh/revoke/challenge respond | no local heuristic auth state |
| Ask-first queue | `GET /api/mcp/ask-first/pending` | empty queue; expired record; generic load error | app load; after approve/deny | must preserve correlation ids |
| Acrobat health chip / tool gate | `GET /api/adapters/acrobat/health` | unavailable; degraded; unsupported capability | app load; manual refresh | tool buttons must follow this route |
## §0E.26 Final non-phantom, suppression, active-scope, migration, and UI-alias rules (authoritative)
### Active-scope must not remain prose-only
Any surface still marked active in DOC3 after this revision must have:
- explicit route or typed contract,
- request and response schema,
- durable-write/read-model rule,
- degraded-state rule,
- and control-backing or read-surface backing rows.
### Deferred-scope must not masquerade as shipped
The removed custom ELNOR wrappers remain out of active build scope. They must not:
- appear as active connector cards,
- appear as installable servers,
- participate in acceptance tests as shipped features,
- or appear in runtime target guidance as available tools.
### PowerPoint / Excel note
If PowerPoint and Excel remain deferred in DOC3, the companion must also state that they are deferred and not part of first-wave required connector completeness.
### Migration/backfill receipts
Any migration or backfill required by this revision must produce a receipt visible through the relevant receipts/history surface. Silent structural rewrites are not allowed.
### Badge truth rule
All connector badges shown in Q must be backed by `MCPServerListResponseSchema`. No badge may be synthesized solely from frontend local state.
### Observation-label alias rule
If any UI text still says `Watch My Actions`, that label is only a presentation alias for selecting a non-`none` `observation_mode` during `POST /api/learn/sessions` creation. It does **not** create a second runtime control, second persisted setting, or separate `POST /api/learn/sessions/:sessionId/observation/*` command family.
### Request-more-tests alias rule
If any UI text still shows `Request More Tests`, that control must dispatch `POST /api/learn/proposals/:proposalId/revise` using `ProposalReviseRequestSchema` with UI-seeded revision instructions requesting additional testing/evidence. It must not imply a separate hidden route.
### Hidden-route rule for ability quarantine surfaces
Ability `activate`, `deactivate`, `quarantine`, and `unquarantine` routes may remain available for admin/repair flows, but they are not required user-facing DOC3 controls in Q. Required Q surfaces must continue to route normal users through proposal install/approve flows instead of exposing those buttons.
## §0E.27 Inherited-control and legacy-surface suppression matrix (authoritative)
| Inherited text / surface | Where it can still appear in retained material | Final disposition | Replacement / required handling |
|---|---|---|---|
| `Request adapter` CTA | older appendix / historical product notes | **Hidden** | no shipped standalone button; use import compatibility report with `requires_adapter = true` and explanatory message |
| Singular learn-route examples (`/api/learn/session/...`) | older appendix / historical route tables | **Informational-only** | all active routes use plural `/api/learn/sessions/...` family |
| Skill drawer `edit` | older product-wireframe text | **Hidden** | no shipped action until a future route-backed redline adds it |
| Skill drawer `duplicate` | older product-wireframe text | **Hidden** | no shipped action until a future route-backed redline adds it |
| Skill drawer `disable` | older product-wireframe text | **Hidden** | normal users use proposal/install flows; no required disable button |
| Skill drawer `delete` | older product-wireframe text | **Hidden** | no shipped action until a future route-backed redline adds it |
| Any Learn detail/read surface whose route is not named in `§2.3A` / `§3.1` | inherited narrative text | **Not shipped** | add a route-backed row first or suppress the surface |
| Any connector card or chip for removed custom ELNOR wrappers | inherited wrapper-planning text | **Hidden** | do not render; only M365 + other active connectors may appear |
### Explicit stale-state/error requirements added by this revision
1. `POST /api/learn/sessions/:sessionId/stop` returning `CAPTURE_ALREADY_STOPPED` must produce:
- inline stale-state banner,
- a `Refresh session state` secondary action,
- no hidden retry,
- and a forced refresh of detail + observation-scope surfaces.
2. Category create/update returning `CATEGORY_LIMIT_REACHED` must produce:
- inline limit banner in the modal/drawer,
- disabled confirm button until the limit issue is resolved,
- no optimistic local category insertion,
- and a refresh of the category list before a second attempt.
### Legacy-appendix suppression note
At the top of any retained Appendix A subsection that repeats route inventories, schema inventories, control tables, or read-surface tables, add:
```md
> LEGACY / NON-OPERATIVE: retained only for historical reading and traceability. Do not implement from this block. Use the newer R3.2 authoritative contract sections instead.
```
### R11.2 partial deployment additions
| Component | If not deployed | Q behavior |
|---|---|---|
| `verify_checkpoint` tool | Checkpoints informational only | "Checkpoint verification not yet available" |
| Checkpoint lint | Warning instead of gate | "Checkpoint lint not available — manual review" |
| DOC10 checkpoint_health | Route using existing health | No visible change |
| Category CRUD | Categories not available | Hide "Add to Category" |
| SSE event stream | Q polls every 5s as fallback | "Real-time updates unavailable" |
| Ability lookup | DOC10 uses generic routing only | Learned skills may not auto-discover |
| Phase 2+ adapters | Show `ADAPTER_UNAVAILABLE` | Suggest alternative capture |
| History route | Tab disabled | "Coming soon" |
| Activate/deactivate/quarantine | Managed via install/approve only | Hide buttons |
**Hard release blockers (must deploy before Learn is user-facing):**
1. Session CRUD routes (create/start/stop/cancel)
2. Proposal install route
3. Skill materialization (§0C.23)
4. Bridge rebuild trigger
5. Availability snapshot refresh
6. `GET /api/learn/runtime/current`
7. At least one Phase 1 observation adapter
---
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 1 — Inherited Baseline — DOC3 Companion Doc Delta Plan R9 [Preserved Below]
# DOC3 Companion Doc Delta Plan — R9 [Canonical Consolidated]
## Revision Lineage (must persist in all later versions)
Based on:
- DOC3 Companion Doc Delta Plan — R8 [Consolidated Current]
- Companion Addendum Proposal R1 — Q Core / EC Core / DOC10 / DOC11 / DOC15 impacts for Actions & Abilities
- DOC3 Self-Learning / Guided Learning Companion Deltas R2
- companion impacts extracted from DOC3 LlamaIndex Integration Additions R1
- companion impacts preserved from ELNOR First-Wave MCP Pack R3
This consolidated current version fully subsumes those prior operative versions and addenda for companion-delta scope.
## Consolidation Rule
This file is the current **single operative DOC3 companion delta plan**.
Precedence in case of overlap is by **topic ownership**, not merely chronology:
1. **Inherited Baseline (R8)** governs all topics unless superseded below.
2. **Actions & Abilities Companion Addendum** governs:
- Q Core/UI information architecture
- Actions / Abilities / Learn browser/pane relationships
- category/collection UI and object-model impacts
- top-level user-facing grouping impacts
3. **Self-Learning / Guided Learning Companion Deltas R2** governs:
- Learn runtime
- LearnSession, observation, proposal lifecycle, later-use activation
- learning receipts / ability availability / runtime and cross-doc wiring
4. **Retrieval Provider / LlamaIndex / MCP Pack Impacts** govern:
- remaining connector/provider/corpus/read-model impacts not already fully captured above
## Included Source Chain
- 1. Inherited Baseline — DOC3 Companion Doc Delta Plan — R8 [Consolidated Current]
- 2. Merged Addendum — Actions & Abilities Companion Addendum R1
- 3. Merged Addendum — Self-Learning / Guided Learning Companion Deltas R2
- 4. Merged Addendum — Retrieval Provider / LlamaIndex / MCP Pack Impacts
## Canonicalization Note
After this merge:
- the source addenda remain useful as historical/source artifacts,
- but they are **not** separate active operative companion-delta docs anymore.
- future red-team and implementation work should target **this file** as the operative companion delta plan.
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 1 — Inherited Baseline — DOC3 Companion Doc Delta Plan R8
# DOC3 Companion Doc Delta Plan — R8 [Consolidated Current]
## Revision Lineage (must persist in all later versions)
Based on DOC3 Companion Doc Delta Plan — R7 [Consolidated Current] plus the merged Learning Runtime / Later-Use Hardening revision below. This consolidated current version fully subsumes those prior operative versions.
## Consolidation Rule
If an inherited baseline statement conflicts with a later merged revision block in this file, the later merged revision block governs.
## Included Source Chain
- 1. Inherited Baseline — DOC3 Companion Doc Delta Plan — R7 [Consolidated Current]
- 2. Merged Revision — DOC3 Companion Doc Delta Plan R7.1 (Learning Runtime / Later-Use Hardening)
# DOC3 Companion Doc Delta Plan — R7 [Consolidated Current]
## Revision Lineage (must persist in all later versions)
Based on DOC3 Companion Doc Delta Plan R6 plus DOC3 Companion Doc Delta Plan R6.1 (Retrieval / Topology Alignment). This consolidated current version fully subsumes those prior operative versions.
## Consolidation Rule
If an inherited baseline statement conflicts with a later merged revision block in this file, the later merged revision block governs.
## Included Source Chain
- 1. Inherited Baseline — DOC3 Companion Doc Delta Plan R6 — source file: `DOC3_Companion_Doc_Delta_Plan_R6.md`
- 2. Merged Revision — DOC3 Companion Doc Delta Plan R6.1 (Retrieval / Topology Alignment) — source file: `DOC3_Companion_Doc_Delta_Plan_R6_1_Retrieval_Topology_Alignment.md`
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 1 — Inherited Baseline — DOC3 Companion Doc Delta Plan R6
# DOC3 Companion Doc Delta Plan R6
**Purpose:** companion-spec changes required to make `DOC3 App Skills R9` implementable without guesswork.
**Status:** normative delta plan for follow-on revisions; not a substitute for the companion documents themselves.
**Primary focus:** accepted red-team hardening, autonomous skill mining, Anthropic/OpenClaw-style skill packaging, hybrid control-surface routing, comprehensive MCP integration, project-aware cloud source resolution, telemetry, and single-writer enforcement.
## 1. Executive summary
DOC3 R9 is now the canonical owner of:
- skill bundles and capability manifests,
- portable AgentSkills-compatible packaging and progressive disclosure,
- hybrid control policy and control-surface ordering,
- teach / trace / promote semantics,
- autonomous skill mining and user-guided skill building,
- MCP connector semantics and local-vs-cloud route class rules,
- skill import, namespacing, collision handling, and install lanes,
- capability health / quarantine / reprobe semantics,
- and the bridge-facing capability artifact model consumed by DOC10.
Companion docs must be updated so that:
- EC remains the sole durable writer,
- OpenClaw remains the runtime truth owner,
- DOC10 consumes the canonical shared contracts instead of redefining them,
- DOC11 reports runtime + connector truth,
- DOC7 supplies support-pack and project-binding infrastructure,
- DOC8 supplies friction and skill-mining triggers,
- DOC9 supplies repair / rollback / adapter proposals,
- DOC15 scores injected context and generated-skill usefulness,
- Q exposes truthful controls and telemetry,
- and ELNOR Core provides project identity, process learning, and promotion ownership.
## 2. Global cross-doc rules added in R9
### 2.1 Shared contracts package is mandatory
Create and treat as canonical:
```text
packages/contracts/src/capabilities/*
packages/contracts/src/mcp/*
packages/contracts/src/skills/*
packages/contracts/src/projects/*
packages/contracts/src/common/*
```
All docs that define or consume these contracts must import the shared canonical schema rather than redefining it locally.
### 2.2 Single writer remains the law
Canonical durable writes remain EC-owned only.
Allowed:
- wrappers / hooks / UI emit intents, proposals, receipts, and traces
- EC validates and writes canonical durable state
- EC projects runtime copies for OpenClaw where required
Disallowed:
- scripts/hooks/direct UI writes to canonical manifests
- direct wrapper edits to canonical connector policy
- direct runtime edits to canonical support-pack or project-binding state
### 2.3 Local-native vs cloud-native route class rule
Companion docs must reflect:
- local app / local file work → native OpenClaw / wrappers / shortcuts / MIDI first
- cloud system-of-record work → MCP / structured connector first
- browser automation last
- project identity lives in Core / DOC7, not in a duplicate DOC3 matter store
### 2.4 Generated skills are proposals first
Companion docs must support the install lanes:
- `pending`
- `experimental_private`
- `approved_workspace`
- `shared_promoted`
No autonomous flow may silently jump to shared/canonical install.
## 3. Required changes by document
## 3.1 DOC1 — Memory Resilience
### Add memory kinds
- `capability_trace`
- `skill_bundle_proposal`
- `connector_receipt`
- `project_binding_hint`
- `support_pack_ref`
- `observed_action_event`
### Schemas
```ts
import { z } from "zod";
export const ConnectorReceiptMemorySchema = z.object({
receipt_id: z.string().uuid(),
capability_id: z.string().max(160),
connector_server_id: z.string().max(120),
provider: z.string().max(80).optional(),
project_id: z.string().max(160).optional(),
action_class: z.enum(["read", "write", "admin"]),
outcome: z.enum(["success", "failure", "denied", "cancelled"]),
created_at: z.string().datetime(),
schema_version: z.literal(1),
});
export const SkillBundleProposalMemorySchema = z.object({
proposal_id: z.string().uuid(),
source_mode: z.enum(["elnor_observed", "user_guided", "desktop_observed"]),
capability_ids: z.array(z.string().max(160)).default([]),
install_lane: z.enum(["pending", "experimental_private", "approved_workspace", "shared_promoted"]),
created_at: z.string().datetime(),
schema_version: z.literal(1),
});
```
### Wiring
- source: DOC3 capability execution, skill mining, MCP receipt emission
- destination: DOC1 memory candidate / trace indexing
- ownership: EC writer only
- degraded mode: if DOC1 update path unavailable, receipts/proposals remain in local artifact logs and are backfilled later
## 3.2 DOC2 — Freshness Manager
### Add
- live connector freshness stamps
- “live as of” vs “cached as of” distinction
- stale-warning rules for generated skills depending on live support packs or connectors
### New artifact
```text
ELNOR_MEMORY/system/freshness/connector_facts_current.json
```
### Schema
```ts
import { z } from "zod";
export const ConnectorFactFreshnessSchema = z.object({
connector_server_id: z.string().max(120),
fact_scope: z.string().max(160),
freshness_kind: z.enum(["live", "cached", "unknown"]),
verified_as_of: z.string().datetime().optional(),
cached_as_of: z.string().datetime().optional(),
schema_version: z.literal(1),
});
```
### Wiring
- source: MCP connector responses and project resolver live fetches
- destination: DOC2 verified-facts / stale-badge logic
- ownership: EC freshness writer
- degraded mode: surface “live freshness unavailable” and never silently mark connector-derived facts as fresh
## 3.3 DOC4 — OpenClaw Bridge / EC bridge
### Add
- preserve `elnor-ec` as the rich-memory/context bridge
- formalize bridge routes for:
- capability bridge/health/stats
- skill import staging
- teach sessions
- autonomous skill mining
- project resolver
- MCP registry/policy/health/receipts
### New route list
```http
GET /api/capabilities/bridge
GET /api/capabilities/health
GET /api/capabilities/stats
POST /api/capabilities/teach/start
POST /api/capabilities/teach/cancel
POST /api/capabilities/teach/finish
POST /api/capabilities/promote
POST /api/skills/import/scan
POST /api/skills/import/stage
POST /api/skills/import/approve
POST /api/skills/import/reject
POST /api/skills/import/install-private
GET /api/skills/import/list
GET /api/skills/mining/settings
POST /api/skills/mining/settings
POST /api/skills/mining/scan
POST /api/skills/mining/proposals/:proposalId/questions
POST /api/skills/mining/proposals/:proposalId/answers
POST /api/skills/mining/proposals/:proposalId/test
POST /api/skills/mining/proposals/:proposalId/install-experimental
POST /api/skills/mining/proposals/:proposalId/feedback
GET /api/skills/mining/proposals
GET /api/mcp/servers
GET /api/mcp/health
GET /api/mcp/receipts
POST /api/mcp/policy/update
POST /api/mcp/auth/challenge/respond
POST /api/mcp/smoke-test
```
### Ownership
- caller: Q / OpenClaw worker / proposal actions / skill-mining jobs
- callee: EC service
- fail closed for all policy-changing and install-lane-changing routes
### Code note
DOC4 should import the shared contracts package rather than re-declare tool/bridge schemas locally.
## 3.4 DOC7 — Context Buckets
### Add
- `support_pack` bucket role
- `project_binding` bucket role or compatible binding fields
- project pointers to:
- SharePoint roots
- OneDrive roots
- Teams channels
- app manuals
- skill support materials
- lint rules preventing generated skills from copying source-of-truth cloud content into buckets unnecessarily
### New schema
```ts
import { z } from "zod";
export const SkillSupportPackSchema = z.object({
pack_id: z.string().max(64),
title: z.string().max(120),
bucket_ids: z.array(z.string().max(160)).default([]),
references: z.array(z.string().max(240)).default([]),
project_binding_ids: z.array(z.string().max(160)).default([]),
schema_version: z.literal(1),
});
```
### Wiring
- source: DOC3 support-pack manifests / project resolver
- destination: DOC7 bucket resolution + lazy context loading
- degraded mode: skills still run without packs, but must disclose `support_pack_unavailable`
### UX
Q should expose support-pack provenance and allow the user to inspect what support materials were consumed by a skill.
## 3.5 DOC8 — Self-Learning / Friction
### Add friction classes
- `trigger_overfire`
- `trigger_underfire`
- `wrong_control_surface`
- `mcp_auth_failure`
- `connector_policy_deny`
- `project_binding_mismatch`
- `tool_shadowing_collision`
- `observation_noise`
- `generated_skill_rejected`
### New enum
```ts
export const FrictionClassSchema = z.enum([
"skill_trigger_miss",
"trigger_overfire",
"trigger_underfire",
"wrong_control_surface",
"mcp_auth_failure",
"connector_policy_deny",
"project_binding_mismatch",
"tool_shadowing_collision",
"observation_noise",
"generated_skill_rejected",
]);
```
### Add autonomous skill candidate miner
DOC8 should own:
- trace clustering
- candidate scoring
- impact-ledger trigger for proposal creation
- suppression/mute logic for noisy candidates
- nightly mining cadence
- observation-mode mining hooks
### Required thresholds
- minimum successful traces
- max variation score
- minimum verification coverage
- zero critical safety failures
- optional positive user-value signal
### Wiring
- source: DOC3 traces, wrapper receipts, MCP receipts, observation events
- destination: `skill_bundle_proposal` generation pipeline
- ownership: EC learning service
- fail-safe: ambiguous candidates remain drafts and never auto-install beyond private experimental lanes
## 3.6 DOC9 — Self-Repair Pipeline
### Add
- repair bundle for imported/generated skills
- adapter-creation proposals for not-quite-portable skill bundles
- connector-health reprobe bundles
- namespace collision repair bundles
- rollback path for experimental/private installs
- repair path from failed generated skill back into proposal revision state
### New schema
```ts
import { z } from "zod";
export const SkillRepairProposalSchema = z.object({
proposal_id: z.string().uuid(),
target_skill: z.string().max(120),
issue_class: z.enum(["lint", "trigger", "binding", "connector", "health", "namespace"]),
patch_ref: z.string().max(240),
smoke_tests: z.array(z.string().max(240)).default([]),
rollback_supported: z.boolean().default(true),
schema_version: z.literal(1),
});
```
### Wiring
- source: DOC3 canary failures / degraded generated skills / failed imports
- destination: DOC9 repair proposals and rollback engine
- ownership: repair engine writes proposals only; EC remains canonical writer on apply
## 3.7 DOC10 — Unified Engagement Orchestration
### Add
- consume the shared `CapabilityRegistryBridgeEntrySchema`
- do not redefine bridge schema locally
- treat `mcp_connector` and `mcp_server` as first-class control surfaces
- support capability states for:
- `staged`
- `imported`
- `needs_adapter`
- `experimental_private`
- add route-trace linkage to capability receipts
- add route-selection by task class:
- cloud source-of-truth vs local app control
### Specific bridge-entry additions
- `preferred_support_pack_ids?: string[]`
- `project_binding_hint?: string`
- `connector_server_ids?: string[]`
- `rollout_lane?: "experimental_private" | "experimental_shared" | "approved" | "quarantined"`
### UX
“What Can I Do Here?” should:
- surface experimental/private/generated skill status honestly,
- explain why a connector was preferred or denied,
- show unavailable reasons when runtime or policy blocks a capability.
## 3.8 DOC11 — OpenClaw Runtime / Model Controls
### Add runtime truth for
- provider-native MCP capability
- ELNOR-mediated MCP availability
- per-provider allow/deny state
- ask-first requirement
- observation service availability
- experimental skill lane visibility
- browser relay detached events
### Example schema
```ts
import { z } from "zod";
export const RuntimeConnectorTruthSchema = z.object({
provider: z.string().max(40),
supports_mcp: z.boolean(),
allowed_servers: z.array(z.string().max(120)).default([]),
denied_servers: z.array(z.string().max(120)).default([]),
ask_first_servers: z.array(z.string().max(120)).default([]),
observation_mode_available: z.boolean().default(false),
schema_version: z.literal(1),
});
```
### Wiring
- source: runtime adapter / provider capability check
- destination: Q connector settings + route planner gating
- ownership: DOC11 runtime truth producer
- degraded mode: runtime truth unavailable => Q must show `runtime_truth_unknown`
## 3.9 DOC12 — Inter-Agent Communication / Rooms
### Add
- room-scoped “current project binding”
- room receipts for connector use
- room-level “nominate this workflow for skill mining”
- room artifact linkage to skill proposals
- policy for whether room-generated proposals are private vs shareable
### New event types
- `connector.used`
- `connector.denied`
- `skill.proposal.created`
- `skill.proposal.review_requested`
- `teach.session.linked`
### UX
Room transcripts should show a lightweight receipt chip when a connector or generated skill was involved, with expandable details.
## 3.10 DOC15 — CIL
### Add payload kinds / signals
- `skill_bundle_proposal`
- `experimental_skill_install`
- `support_pack_consumed`
- `generated_skill_used`
- `generated_skill_rejected`
- `connector_receipt_used`
- `wrong_surface_overridden`
### Evaluation metrics
- generated-skill usefulness
- post-install adoption
- rejection/override rate
- support-pack usefulness
- whether generated skill actually reduces steps or friction
### Wiring
- source: DOC3 receipts, proposal lifecycle, support-pack telemetry
- destination: CIL scoring
- ownership: CIL reads events; does not mutate canonical skill state directly
## 3.11 Q UI spec
### Add pages/components
- Skills & Connectors settings
- Connector settings page
- Skill import wizard
- Skill compatibility panel
- Teach Elnor panel
- Learn From This action flow
- Pre-build Question modal
- Skill Proposal Review drawer
- Capability awareness card
- Receipts list + detail sheet
- Observation banner / toggle
- Capability/connector health badges and detailed tooltips
### Required UI states
For each major surface:
- loading
- empty
- error
- populated
- degraded
- permission_denied
- partial_deployment
### Required actions
- allow once
- allow for session
- allow for project
- deny
- revise with Elnor
- install privately
- approve shared
- request adapter
- request more tests
- turn off provider MCP
- turn off observation mode
## 3.12 ELNOR Core canonical spec
### Add
- explicit mapping from process memory / mature templates to `skill_bundle_proposal`
- proposal lineage back to template IDs and trace clusters
- confidence contribution from repeated success + user feedback + post-install adoption
- promotion gating and materializer ownership
- command-queue path for `ConfigurationIntent` writes
- project identity remains canonical here, not in DOC3
### New rule
ELNOR Core may generate or endorse `skill_bundle_proposal` artifacts, but canonical promotion to approved/shared skill remains approval-gated unless an explicit private experimental mode is configured.
## 4. Shared code implementation guidance for coding agents
## 4.1 Packages to create first
```text
packages/contracts/src/capabilities/
packages/contracts/src/mcp/
packages/contracts/src/skills/
packages/contracts/src/projects/
packages/contracts/src/common/
```
## 4.2 EC modules to add
```text
apps/ec-service/src/capabilities/build-bridge.ts
apps/ec-service/src/capabilities/write-bridge.ts
apps/ec-service/src/capabilities/project-manifest.ts
apps/ec-service/src/capabilities/resolve-availability.ts
apps/ec-service/src/capabilities/probe-health.ts
apps/ec-service/src/capabilities/trace-recorder.ts
apps/ec-service/src/capabilities/teach-session.ts
apps/ec-service/src/capabilities/promote-template.ts
apps/ec-service/src/capabilities/hybrid-planner.ts
apps/ec-service/src/capabilities/project-resolver.ts
apps/ec-service/src/skills/import/scan-bundle.ts
apps/ec-service/src/skills/import/lint-bundle.ts
apps/ec-service/src/skills/import/stage-bundle.ts
apps/ec-service/src/skills/import/materialize-bundle.ts
apps/ec-service/src/skills/import/namespace-tools.ts
apps/ec-service/src/skills/mining/candidate-miner.ts
apps/ec-service/src/skills/mining/draft-skill-bundle.ts
apps/ec-service/src/skills/mining/run-canary-tests.ts
apps/ec-service/src/mcp/auth/load-profile.ts
apps/ec-service/src/mcp/policy/evaluate-policy.ts
apps/ec-service/src/mcp/routing/resolve-route.ts
apps/ec-service/src/mcp/health/update-health.ts
apps/ec-service/src/mcp/receipts/write-receipt.ts
apps/ec-service/src/mcp/providers/openai.ts
apps/ec-service/src/mcp/providers/anthropic.ts
apps/ec-service/src/mcp/providers/codex.ts
apps/ec-service/src/mcp/providers/perplexity.ts
apps/ec-service/src/mcp/providers/m365.ts
apps/ec-service/src/mcp/providers/custom.ts
apps/ec-service/src/mcp-servers/project-server.ts
apps/ec-service/src/mcp-servers/knowledge-server.ts
apps/ec-service/src/mcp-servers/local-files-server.ts
```
## 4.3 Frontend modules to add
Use `q-frontend`, not `q-web`.
```text
apps/q-frontend/src/features/skills/SkillMiningSettingsPanel.tsx
apps/q-frontend/src/features/skills/PreBuildQuestionsModal.tsx
apps/q-frontend/src/features/skills/SkillProposalReviewDrawer.tsx
apps/q-frontend/src/features/skills/SkillImportWizard.tsx
apps/q-frontend/src/features/skills/SkillCompatibilityPanel.tsx
apps/q-frontend/src/features/connectors/ConnectorSettingsPage.tsx
apps/q-frontend/src/features/connectors/ConnectorSettingsPanel.tsx
apps/q-frontend/src/features/connectors/ConnectorHealthBadge.tsx
apps/q-frontend/src/features/connectors/MCPReceiptCard.tsx
apps/q-frontend/src/features/connectors/ConnectorReceiptDetailSheet.tsx
apps/q-frontend/src/features/capabilities/CapabilityAwarenessCard.tsx
apps/q-frontend/src/features/capabilities/CapabilityReceiptList.tsx
```
## 4.4 Middleware and auth
Add:
- privilege middleware for skills/capabilities/MCP routes
- canonical error envelope
- no raw secret/token material in ELNOR memory
- auth profiles use secret references only
## 4.5 Partial deployment rules
If companion docs ship later than DOC3:
- show degraded / partial deployment states in Q
- block destructive connector actions
- allow manual Teach Elnor where safe
- do not auto-promote generated skills if bridge/support-pack/runtime routes are absent
## 5. Implementation sequencing
### Phase A — contracts and enforcement
- shared contracts package
- canonical write guard
- error envelope
- import state machine
- route auth middleware
### Phase B — DOC3 substrate
- manifests
- bridge build/write
- teach sessions
- proposal bundles
- support-pack links
- project resolver
### Phase C — UI shells
- teach panel
- proposal review drawer
- connector settings page
- receipts detail sheet
- capability card
### Phase D — MCP operational layer
- auth profiles
- policy evaluator
- route scoring
- health updater
- receipts
- first Microsoft pack
### Phase E — autonomous skill mining
- candidate miner
- observation ingestion
- pre-build questions
- build/test/install lanes
### Phase F — companion hardening
- DOC7 support-pack backend
- DOC8 friction taxonomy
- DOC9 repair bundles
- DOC15 usefulness scoring
## 6. Final rule
When there is a conflict:
1. shared contract package wins for schemas,
2. EC wins for canonical durable writes,
3. DOC11 wins for runtime truth,
4. DOC10 consumes capability read-models but does not redefine emitter contracts,
5. DOC3 defines skill/capability semantics and packaging,
6. Q reflects and controls, but does not invent runtime state.
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 2 — Merged Revision — DOC3 Companion Doc Delta Plan R6.1 (Retrieval / Topology Alignment)
# DOC3 Companion Doc Delta Plan R6.1
## Retrieval Provider and Graph/Topology Alignment Addendum
**Purpose:** companion-spec changes required to make `DOC3 App Skills R9.1` implementable without guesswork.
**Status:** normative delta plan for follow-on revisions; not a substitute for the companion documents themselves.
**Primary focus:** retrieval-lane truth, LlamaIndex sidecar routing, corpus bindings, retrieval receipts, graph/topology boundary alignment, and the downstream contracts required by DOC3’s new retrieval-owner rules.
---
## 1. Executive summary
DOC3 R9.1 now becomes the canonical owner of:
- retrieval-lane doctrine,
- provider-kind truth for `llamaindex_index`,
- retrieval corpus bindings/hints at the capability layer,
- provider-level retrieval receipt contracts,
- bounded adaptive route learning for semantic corpus routes,
- and explicit non-goals preventing LlamaIndex or any indexed provider from becoming canonical memory or graph truth.
Companion docs must be updated so that:
- EC remains the sole durable writer,
- DOC18 owns the LlamaIndex sidecar build and provider-specific health/truth,
- DOC10 consumes retrieval receipts and shows route/provider truth coherently,
- DOC11 keeps native/runtime search truth distinct from EC canonical-memory search,
- DOC7 consumes corpus/support-pack/document-priority hints without bloating context,
- DOC15 consumes retrieval receipts and corpus/topology hints without becoming graph owner,
- ELNOR Core/DocIndex can eventually expose broader topology read-models without conflicting with DOC18,
- and Q exposes truthful controls, provider health, stale/degraded truth, and compare-route debugging.
---
## 2. Global cross-doc rules added in R6.1
### 2.1 Shared retrieval contracts package is mandatory
Create and treat as canonical:
```text
packages/contracts/src/retrieval/provider-receipts.ts
packages/contracts/src/retrieval/search-provider-kinds.ts
packages/contracts/src/retrieval/corpus-bindings.ts
packages/contracts/src/retrieval/preferences.ts
packages/contracts/src/retrieval/llamaindex.ts
```
All docs that define or consume retrieval provider truth must import the shared canonical schemas rather than redefining them locally.
### 2.2 Single writer remains the law
Canonical durable writes remain EC-owned only.
Allowed:
- sidecar emits query results, health, and corpus facts,
- EC validates and writes current views, route traces, receipts, and policies,
- UI emits intents/commands only.
Disallowed:
- sidecar writing canonical memory,
- sidecar writing project identity,
- sidecar writing graph truth,
- UI or wrappers mutating corpus-binding truth directly.
### 2.3 Retrieval-lane separation is mandatory
Companion docs must reflect:
- exact/live retrieval != semantic corpus retrieval,
- semantic corpus retrieval != canonical memory retrieval,
- canonical memory retrieval != OpenClaw native runtime/local search,
- browser fallback remains last.
### 2.4 Graph/topology remains a derived read-model
Companion docs must support:
- provider metadata and receipts that can feed graph/topology consumers,
- but no redefinition of graph truth inside DOC3 or DOC18.
---
## 3. Required changes by document
## 3.1 DOC1 — Memory Resilience
### Add / clarify
- If DOC1 stores any retrieval-related memory artifacts, it should store **receipts or relation facts**, not let provider truth mutate canonical memory ownership.
- Keep the existing memory relationship index as-is unless/until explicitly expanded; broader graph/topology stays outside DOC1 for now.
- Expose a bounded read/query seam over relationship-index traversal for consumers that need one-hop relation-aware explanation/ranking.
### Suggested schema addition
```ts
import { z } from "zod";
export const RetrievalReceiptMemorySchema = z.object({
receipt_id: z.string().uuid(),
provider_kind: z.string().max(80),
search_lane: z.string().max(80),
project_id: z.string().max(120).optional(),
matter_id: z.string().max(120).optional(),
corpus_ids: z.array(z.string().max(120)).default([]),
route_reason_codes: z.array(z.string().max(120)).default([]),
freshness_state: z.enum(["fresh", "stale", "unknown"]).default("unknown"),
created_at: z.string().datetime(),
schema_version: z.literal(1),
});
```
### Wiring
- source: DOC3 retrieval route execution / DOC18 provider receipts
- destination: optional DOC1 memory traces and one-hop relation-aware explanation support
- degraded mode: if DOC1 write path unavailable, route receipts remain in DOC10/EC trace storage and backfill later
---
## 3.2 DOC2 — Freshness Manager
### Add
- corpus freshness stamps for indexed providers,
- live-vs-indexed truth distinction,
- stale-warning rules for semantic corpus results,
- degraded warnings when sidecar freshness cannot be verified.
### New artifact
```text
ELNOR_MEMORY/system/freshness/retrieval_provider_facts_current.json
```
### Suggested schema
```ts
import { z } from "zod";
export const RetrievalProviderFreshnessSchema = z.object({
provider_kind: z.string().max(80),
corpus_id: z.string().max(120).optional(),
freshness_kind: z.enum(["live", "indexed", "cached", "unknown"]),
verified_as_of: z.string().datetime().optional(),
stale: z.boolean().default(false),
stale_reason: z.string().max(240).optional(),
schema_version: z.literal(1),
});
```
---
## 3.3 DOC4 — OpenClaw Bridge / EC bridge
### Add
- preserve `elnor-ec` as the bridge for route/provider current views and retrieval receipts when OpenClaw or Q needs them,
- do not route EC canonical-memory search through OpenClaw by default,
- keep runtime/native search and EC retrieval truth separate in bridge language.
### New route list additions
```http
GET /api/retrieval/providers
GET /api/retrieval/providers/health
GET /api/retrieval/corpora
POST /api/retrieval/corpora/:corpusId/refresh
GET /api/retrieval/receipts
POST /api/retrieval/debug/compare-routes
```
### Ownership
- caller: Q / OpenClaw worker / advanced debug surfaces
- callee: EC service
- fail closed for policy-changing routes
---
## 3.4 DOC7 — Context Buckets
### Add
- `retrieval_corpus_hints` as an accepted input into document/materialization planning,
- graph-aware `document_priority_hints`,
- support-pack grouping metadata,
- bounded reason codes such as `same_issue`, `same_matter`, `support_pack_member`, `active_review_target_neighbor`.
### New schema
```ts
import { z } from "zod";
export const DocumentPriorityHintSchema = z.object({
doc_id: z.string().max(160),
priority: z.enum(["critical", "useful", "background"]).default("useful"),
reason_codes: z.array(z.string().max(120)).default([]),
support_pack_group_id: z.string().max(120).optional(),
schema_version: z.literal(1),
});
```
### Wiring
- source: DOC3 retrieval hints / DOC15 graph-aware recommendations / future topology read-model
- destination: DOC7 bucket resolution and bounded materialization
- degraded mode: treat graph-aware reasons as absent; never break baseline bucket behavior
---
## 3.5 DOC10 — Unified Engagement Orchestration
### Add
- canonical route-trace fields for retrieval receipts,
- unified provider/lane display surfaces in Q,
- compare-route debug action and read-models,
- route traces that preserve `provider_kind`, `search_lane`, `corpus_ids`, `freshness_state`, `degraded_reason`, and `route_reason_codes`.
### New artifacts
```text
ELNOR_MEMORY/system/orchestration/retrieval_receipts.jsonl
ELNOR_MEMORY/system/orchestration/retrieval_routes_current.json
```
### Suggested schema
```ts
import { z } from "zod";
export const RouteRetrievalOverlaySchema = z.object({
provider_kind: z.string().max(80),
search_lane: z.string().max(80),
corpus_ids: z.array(z.string().max(120)).default([]),
route_reason_codes: z.array(z.string().max(120)).default([]),
freshness_state: z.enum(["fresh", "stale", "unknown"]).default("unknown"),
degraded_reason: z.string().max(240).optional(),
schema_version: z.literal(1),
});
```
### UI
- receipt chips for retrieval provider/lane truth
- advanced panel: why-this-route, compare-route, stale/degraded explanation
- provider/corpus health page or section
---
## 3.6 DOC11 — Gateway / runtime truth
### Add
- explicit rule that OpenClaw native semantic/local search and EC-owned canonical-memory retrieval are separate systems,
- runtime truth exports may mention native/local search availability, but do not claim ownership over EC provider truth,
- `ContextInjectionManifest` / related read models may render retrieval overlays when EC supplies them.
### Required rule
Do not imply that a Gateway/OpenClaw native path is the owner of all semantic retrieval just because it can perform local search.
---
## 3.7 DOC15 — CIL / MemorySearchService / ContextPlanner
### Add
- retrieval receipt / provider truth fields in advisory and suggestion explanation surfaces,
- consumption of `retrieval_corpus_hints`,
- graph-aware document suggestions and support-pack hints,
- future `MemorySearchService` seam note that preserves canonical-memory retrieval ownership outside DOC18.
### Wiring
- source: DOC3 receipts and hints / DOC18 provider truth / Core/DocIndex topology read-model
- destination: CIL ranking, advisor explanations, document suggestion surfaces
- degraded mode: if graph/topology unavailable, CIL falls back to baseline ranking and says so
---
## 3.8 ELNOR Core / DocIndex
### Add / preserve
- corpus-binding current views written by EC,
- provider-health current views,
- future topology read-model snapshots/build jobs,
- stable aliases for documents/nodes that downstream consumers can resolve,
- no silent conversion of provider metadata into canonical graph truth.
### New artifacts (eventual)
```text
ELNOR_MEMORY/system/retrieval/llamaindex/corpus_bindings_current.json
ELNOR_MEMORY/system/retrieval/llamaindex/provider_health_current.json
ELNOR_MEMORY/system/topology/topology_snapshot_current.json
ELNOR_MEMORY/system/topology/topology_health_current.json
```
---
## 3.9 Q / dashboard surfaces
### Add
- retrieval provider settings,
- corpora management surface,
- retrieval receipt panel,
- compare-route debug view,
- provider/corpus health chips,
- route explanation tooltips.
### Rule
Advanced retrieval debugging may exist, but the normal user path must stay readable and not turn into a telemetry cockpit.
---
## 3.10 DOC18 — LlamaIndex Retrieval Sidecar
### Add / preserve
- sidecar provider health/current-view export contracts,
- provider receipt fields,
- corpus health snapshot endpoint,
- route reason codes,
- topology boundary note,
- non-goal language preventing drift into memory/identity/graph ownership.
---
## 4. Files, modules, and endpoints to add
### Shared contracts
```text
packages/contracts/src/retrieval/provider-receipts.ts
packages/contracts/src/retrieval/search-provider-kinds.ts
packages/contracts/src/retrieval/corpus-bindings.ts
packages/contracts/src/retrieval/preferences.ts
packages/contracts/src/retrieval/llamaindex.ts
```
### EC service
```text
apps/ec-service/src/retrieval/providers/llamaindex-client.ts
apps/ec-service/src/retrieval/receipt/write-retrieval-receipt.ts
apps/ec-service/src/retrieval/providers/provider-health.ts
apps/ec-service/src/retrieval/corpora/current-views.ts
apps/ec-service/src/retrieval/debug/compare-routes.ts
```
### HTTP surface additions
```http
GET /api/retrieval/providers
GET /api/retrieval/providers/health
GET /api/retrieval/corpora
POST /api/retrieval/corpora/:corpusId/refresh
GET /api/retrieval/receipts
POST /api/retrieval/debug/compare-routes
```
---
## 5. Acceptance criteria
The DOC3 companion plan R6.1 is complete on this topic only when:
1. Companion docs can all point to the same shared retrieval contracts package.
2. No companion doc implies that `llamaindex_index` is canonical memory or project identity.
3. DOC10 can display provider/lane truth and compare-route debugging without guessing fields.
4. DOC15 can consume retrieval receipts and corpus hints without inventing provider ownership.
5. DOC11 preserves the native/runtime vs canonical-memory distinction.
6. DOC7 can consume graph-aware hints in a bounded way.
7. ELNOR Core/DocIndex can later expose topology snapshots without conflicting with DOC18.
8. Coding agents can tell which doc owns which piece of retrieval/provider truth.
---
## 6. Recommended decision for Wave B
Treat this R6.1 addendum as the narrow companion delta needed for the retrieval/topology amendment wave.
It does **not** require rewriting every companion doc at once. It tells the next owner-doc revisions exactly what they must absorb so that:
- provider truth is consistent,
- lane truth is consistent,
- receipts are renderable,
- graph/topology remains derived,
- and LlamaIndex stays powerful without mutating into a second hidden memory system.
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 3 — Merged Revision — DOC3 Companion Doc Delta Plan R7.1 (Learning Runtime / Later-Use Hardening)
# DOC3 Companion Doc Delta Plan R7.1
## Learning Runtime, Ability Availability, and Guided Learning Hardening Addendum
**Purpose:** companion-spec changes required to make the DOC3 self-learning / guided-learning runtime actually work end to end.
**Status:** normative merged revision for the consolidated companion delta plan.
**Primary focus:** LearnSession lifecycle, observation adapters, semantic labeling, proposal continuity, activation lifecycle, Ability Availability Snapshot, and later-use routing.
## 1. Executive summary
DOC3 now requires companion docs to support not only skill generation, but also the complete learning runtime:
- entering learning modes,
- capturing bounded workflows,
- proposing and testing learned abilities,
- installing them into the correct lane,
- exposing them to Elnor later,
- and surfacing the whole lifecycle to the user with receipts.
The most important additions in this merged revision are:
- a canonical LearnSession lifecycle,
- deep-link payloads for learning review continuity,
- proposal pinning / active-target continuity,
- runtime Ability Availability Snapshot support,
- activation/deactivation/quarantine lifecycle,
- observation adapter truth,
- and explicit later-use route lookup.
## 2. Global rules added by R7.1
### 2.1 Shared learning contracts are mandatory
In addition to the existing shared contracts package, create and treat as canonical:
```text
packages/contracts/src/learning/learn-session.ts
packages/contracts/src/learning/observation-adapter.ts
packages/contracts/src/learning/observed-action.ts
packages/contracts/src/learning/boundary.ts
packages/contracts/src/learning/clarification.ts
packages/contracts/src/learning/query-context.ts
packages/contracts/src/learning/document-deps.ts
packages/contracts/src/learning/receipts.ts
packages/contracts/src/capabilities/availability-snapshot.ts
packages/contracts/src/capabilities/activation.ts
packages/contracts/src/workflows/workflow-graph.ts
```
All docs that define or consume learning runtime state must import these schemas rather than redefining them.
### 2.2 Learn surfaces and learn mechanisms must be distinct
Companion docs must explicitly distinguish:
- Learn UI entry points,
- Learn runtime/session objects,
- proposal lifecycle,
- ability later-use and activation.
### 2.3 A learned ability is not complete until it is later-usable
Companion docs must support the later-use chain:
```text
LearnSession
-> proposal
-> validation
-> install lane
-> manifest/materialization
-> ability availability snapshot
-> bridge rebuild
-> DOC10 awareness
-> later-use by Elnor
```
### 2.4 Proposal continuity is mandatory
Long review/teach sessions must preserve the active learning target via pinning and deep-link payloads.
## 3. Required changes by document
## 3.1 ELNOR Core canonical spec
### Add
- `LearnSession` as first-class object
- `SkillBundleProposal` as first-class learning artifact
- install lane ownership
- activation lifecycle ownership
- later-use projection ownership
- proposal pinning state
- command queue / configuration-intent path for learning transitions
### Import these schemas
- `LearnSessionSchema`
- `SkillBundleProposalSchema`
- `SkillValidationReportSchema`
- `AbilityLifecycleCommandSchema`
- `AbilityAvailabilitySnapshotSchema`
### Why
Core must own the semantic meaning of proposals and their transition into usable abilities.
## 3.2 DOC4 — OpenClaw Bridge / EC bridge
### Add routes
```http
POST /api/learn/session/start
POST /api/learn/session/pause
POST /api/learn/session/resume
POST /api/learn/session/stop
POST /api/learn/session/cancel
GET /api/learn/session/:id
POST /api/learn/session/:id/mark-goal
POST /api/learn/session/:id/mark-step
POST /api/learn/session/:id/trim
POST /api/learn/session/:id/generate-proposal
GET /api/learn/proposals
GET /api/learn/proposals/:id
POST /api/learn/proposals/:id/questions
POST /api/learn/proposals/:id/answers
POST /api/learn/proposals/:id/test
POST /api/learn/proposals/:id/install-private
POST /api/learn/proposals/:id/approve
POST /api/learn/proposals/:id/reject
POST /api/learn/proposals/:id/revise
GET /api/learn/receipts
GET /api/abilities/availability
POST /api/abilities/:id/activate
POST /api/abilities/:id/deactivate
POST /api/abilities/:id/quarantine
POST /api/abilities/:id/promote-shared
```
### Bridge rule
`elnor-ec` must pass `LearningQueryContextPayload` through intact and never strip proposal/session IDs.
## 3.3 DOC7 — Context Buckets
### Add
- support-pack dependency declarations for learned abilities
- project-binding references usable by Learn sessions
- keep raw observation streams out of ordinary bucket content
- support-pack provenance visible to learning review surfaces
## 3.4 DOC8 — Self-Learning / Friction
### Add friction classes
- `boundary_misdetected`
- `semantic_label_ambiguous`
- `proposal_not_routable`
- `ability_not_found_at_runtime`
- `learned_skill_unused`
### Add ownership
DOC8 owns:
- candidate miner thresholds
- proposal suppression/mute logic
- observation noise scoring
- “proposal succeeded but never reused” detection
## 3.5 DOC9 — Self-Repair Pipeline
### Add
- repair bundles for bad learn boundaries
- semantic relabeling proposals
- failed install rollback
- re-draft from quarantined ability to proposal state
- repair path for “ability not found at runtime”
## 3.6 DOC10 — Unified Engagement Orchestration
### Add
- consume `AbilityAvailabilitySnapshot`
- route lookup across:
- approved/shared abilities
- experimental/private abilities
- connector-backed capabilities
- task templates
- explicit rule for when Elnor should look for a learned ability before defaulting to direct action
- route/receipt linkage to learning receipts
### New artifacts
```text
ELNOR_MEMORY/system/orchestration/ability_availability_current.json
ELNOR_MEMORY/system/orchestration/learning_receipts.jsonl
```
## 3.7 DOC11 — Runtime truth
### Add runtime truth for
- observation adapter availability
- learn mode availability
- private-install lane loadability
- ability usability in the current runtime
- ability snapshot freshness
### Why
If runtime truth cannot answer whether the learned ability is usable now, the UI and routing will lie.
## 3.8 DOC12 — Rooms / review continuity
### Add
- room-scoped LearnSession links
- active proposal pinning
- learning review target pinning
- room events for learning lifecycle changes
### Why
Long review sessions will otherwise lose the active target.
## 3.9 DOC15 — CIL / scoring / payloads
### Add
- `LearningQueryContextPayload`
- learning usefulness scoring
- adoption and later-use metrics
- proposal pinning / review continuity semantics parallel to existing deep-link patterns
## 3.10 Q UI / Q Core
### Add
- Learn home/dashboard
- session overlay or global controls
- recent run picker
- observation banner
- proposal review drawer
- questions panel
- timeline trim/review UI
- experimental/private learned ability list
- learning receipts feed
- ability availability panel
- activation controls
### Required states
- idle
- armed
- capturing
- paused
- stopped
- reviewing
- awaiting_questions
- testing
- ready_for_review
- installing_private
- installed_private
- approved
- rejected
- cancelled
- quarantined
- partial_deployment
## 4. Shared implementation guidance
### Backend modules to add
```text
apps/ec-service/src/learning/session-service.ts
apps/ec-service/src/learning/state-machine.ts
apps/ec-service/src/learning/observation-adapters/browser.ts
apps/ec-service/src/learning/observation-adapters/accessibility.ts
apps/ec-service/src/learning/observation-adapters/shortcut.ts
apps/ec-service/src/learning/observation-adapters/midi.ts
apps/ec-service/src/learning/observation-adapters/process.ts
apps/ec-service/src/learning/trace-normalizer.ts
apps/ec-service/src/learning/cluster-service.ts
apps/ec-service/src/learning/clarification-service.ts
apps/ec-service/src/learning/proposal-builder.ts
apps/ec-service/src/learning/test-runner.ts
apps/ec-service/src/learning/install-service.ts
apps/ec-service/src/learning/receipt-writer.ts
apps/ec-service/src/capabilities/ability-availability-snapshot.ts
apps/ec-service/src/capabilities/ability-lookup.ts
apps/ec-service/src/capabilities/install-lane-filter.ts
apps/ec-service/src/capabilities/activation-service.ts
```
### Frontend modules to add
```text
apps/q-frontend/src/features/learn/LearnHomePage.tsx
apps/q-frontend/src/features/learn/LearnSessionOverlay.tsx
apps/q-frontend/src/features/learn/LearnSessionTimeline.tsx
apps/q-frontend/src/features/learn/RecentRunPicker.tsx
apps/q-frontend/src/features/learn/ObservationModeBanner.tsx
apps/q-frontend/src/features/learn/ProposalReviewDrawer.tsx
apps/q-frontend/src/features/learn/LearningQuestionsPanel.tsx
apps/q-frontend/src/features/learn/ExperimentalLearnedAbilitiesView.tsx
apps/q-frontend/src/features/learn/LearningReceiptsFeed.tsx
apps/q-frontend/src/features/abilities/AbilityAvailabilityPanel.tsx
apps/q-frontend/src/features/abilities/AbilityActivationControls.tsx
```
## 5. Partial deployment rule
If learning companion surfaces ship later than DOC3:
- Learn pages must show `partial_deployment`
- install/promote actions must fail closed
- observation mode must be disabled unless adapter truth is available
- ability later-use must not claim success unless Ability Availability Snapshot exists
## 6. Final rule
When there is a conflict:
1. shared learning contracts win,
2. EC owns canonical learning state,
3. DOC11 owns runtime truth,
4. DOC10 owns ability awareness consumption and route lookup,
5. DOC3 defines learning semantics and packaging,
6. Q makes the learning system visible and actionable,
7. DOC15 supplies deep-link explanation and learning quality scoring,
8. DOC12 preserves continuity of active learning targets.
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 2 — Merged Addendum — Actions & Abilities Companion Addendum R1
# Companion Addendum Proposal R1 — Q Core / EC Core / DOC10 / DOC11 / DOC15 impacts for Actions & Abilities
**Purpose:** Capture the non-DOC3 document impacts required by the Actions & Abilities / Categories / Learn-UX decisions so these changes are not lost when the next full revision is prepared.
## 1. Q Core UI Spec changes
### Add the `Actions & Abilities` top-level area
Q Core should define:
- left rail item: Actions & Abilities
- second-column browser behavior
- main center pane behavior
- right-pane interaction relationship
### Add browser rules
The browser should support:
- hierarchical groups
- category filters
- search
- stars/favorites
- drag/drop to category
- right-click Add to Category…
### Add page models
Q Core should define pages for:
- Actions landing page
- Tasks page
- Automations page
- Abilities landing page
- Skills page
- Connectors page
- Learn page
### Add Learn page interactions
Need exact UI definitions for:
- Demonstrate Workflow
- Learn from Recent Run
- Observe My Actions
- Figure It Out and Learn
- Improve Existing Skill
## 2. ELNOR Core / EC Core changes
### Add shared object model
Core should define:
- TaskTemplate
- TaskInstance
- Skill
- Bundle
- SkillProposal
- LearnSession
### Add workflow graph IR ownership
Core should define or share ownership of the workflow graph model used by:
- tasks
- skills
- proposals
- automations
### Add learn-session ownership
Core should own:
- session lifecycle
- promotion transitions
- linkage from Learn page to skill/task objects
- proposal state changes
## 3. DOC10 changes
### Add user-facing ability routing display
DOC10 should display:
- whether the selected object is an Action vs Ability
- whether a skill is atomic vs composite
- whether a connector is involved
- whether the object is experimental/generated/imported
### Add bundle/category awareness
DOC10 does not need to own categories, but should be able to display:
- bundle membership
- categories
- source
- current install lane
## 4. DOC11 changes
### Add runtime truth for:
- active experimental/generated skills
- observation mode on/off
- active connectors used by focused skills/tasks
- active automations/heartbeat jobs
### Add UI coordination
Q should not show an ability as active/usable if DOC11 says it is not currently available.
## 5. DOC15 changes
### Add scoring for:
- generated skill usefulness
- category usage if relevant
- bundle usefulness
- whether Learn actions convert into accepted abilities
- whether task templates or skills are more effective for repeated workflows
## 6. DOC9 changes
### Add repair handling for:
- bundles
- generated composite skills
- category metadata if it becomes corrupt
- task/skill graph conversion issues
## 7. DOC7 changes
### Optional support
DOC7 may need:
- support-pack references for bundles
- project-aware category hints
- Learn/skill-related support material references
DOC7 should not own categories directly unless there is a strong reason.
## 8. Key implementation guidance
### Keep these separate internally
- Task
- Skill
- Connector
- Bundle
- LearnSession
- Category
### Keep these unified in the UI
- Actions & Abilities overall area
- browser interactions
- category assignment
- main-pane work management
### Core non-negotiable
Do not collapse tasks and skills into one object.
They may share a workflow graph, but they should remain distinct object types.
## 9. Recommended next-step integration order
1. Update Q Core IA / browser/main-pane model
2. Update Core object model and workflow graph semantics
3. Update DOC3 ability semantics
4. Update Learn page / proposal lifecycle
5. Update routing/awareness surfaces
6. Update repair/scoring docs
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 3 — Merged Addendum — Self-Learning / Guided Learning Companion Deltas R2
# DOC3 Self-Learning / Guided Learning Companion Deltas R2
**Purpose:** required companion-spec changes to make the DOC3 self-learning / guided-learning runtime actually work end to end.
**Status:** normative delta plan for the next companion-doc update wave.
**Primary focus:** LearnSession runtime lifecycle, observation adapters, proposal pinning, deep-link payloads, activation lifecycle, ability availability snapshots, and later-use routing.
---
## 1. Executive summary
R1 identified most of the right companion docs. R2 makes the cross-doc ownership and wiring much more precise.
The critical new conclusion is:
> DOC3 can define the learning semantics, but the system will not work unless companion docs explicitly supply:
> - runtime truth,
> - ability availability,
> - proposal continuity,
> - deep-link payloads,
> - activation commands,
> - UI realization,
> - and observability.
The most important additions required outside DOC3 are:
- **ELNOR Core**: proposal ownership, install lanes, activation lifecycle
- **DOC4**: concrete routes for learn sessions, proposals, activation, receipts
- **DOC10**: Ability Availability Snapshot consumption and route lookup
- **DOC11**: adapter/runtime truth for learning and observation
- **DOC12**: active proposal pinning and review continuity
- **DOC15**: deep-link payload model and learning usefulness scoring
- **Q Core/UI**: the actual Learn surfaces, overlays, receipts, and later-use views
---
## 2. Global cross-doc rules added in R2
### 2.1 Shared contracts package additions are mandatory
In addition to existing `packages/contracts/src/*`, add:
```text
packages/contracts/src/learning/learn-session.ts
packages/contracts/src/learning/observation-adapter.ts
packages/contracts/src/learning/observed-action.ts
packages/contracts/src/learning/boundary.ts
packages/contracts/src/learning/clarification.ts
packages/contracts/src/learning/query-context.ts
packages/contracts/src/learning/document-deps.ts
packages/contracts/src/learning/receipts.ts
packages/contracts/src/capabilities/availability-snapshot.ts
packages/contracts/src/capabilities/activation.ts
packages/contracts/src/workflows/workflow-graph.ts
```
All companion docs that define or consume learning/runtime availability must import these shared schemas, not re-declare them.
### 2.2 Single writer remains the law
Allowed:
- UI emits commands/intents
- observation adapters emit events
- sidecars emit provider receipts
- EC writes canonical session/proposal/ability state
- EC projects runtime copies as needed
Disallowed:
- adapters writing canonical learning state directly
- UI directly mutating proposal/install lane state
- runtime or wrapper writing ability availability truth directly
### 2.3 Learn surfaces are not equivalent to learn runtime
Companion docs must distinguish:
- Learn UI entry points
- Learn runtime/session objects
- Proposal lifecycle
- Ability activation/use later
That distinction must be explicit in Q UI, DOC10, DOC11, and Core.
### 2.4 Ability availability is a first-class read model
The system must expose a runtime-readable Ability Availability Snapshot.
If this does not exist, learned abilities may never be usable later even if they were successfully created.
---
## 3. Required changes by document
## 3.1 ELNOR Core canonical spec
### Add
1. `LearnSession` as a first-class object
2. `SkillBundleProposal` as a first-class learning artifact
3. `AbilityLifecycleCommand` ownership
4. install lane semantics
5. approval-gated shared promotion
6. private experimental install semantics
7. projection trigger ownership
8. ability availability snapshot materialization ownership
### New schemas to import/use
- `LearnSessionSchema`
- `SkillBundleProposalSchema`
- `SkillValidationReportSchema`
- `AbilityLifecycleCommandSchema`
- `AbilityAvailabilitySnapshotSchema`
### Required rule
Core owns:
- semantic meaning of proposals
- install lane transitions
- promotion to shared
- ability activation history
- projection triggers to workspace and bridge
### Required service additions
```text
apps/ec-service/src/learning/session-service.ts
apps/ec-service/src/learning/proposal-service.ts
apps/ec-service/src/learning/install-service.ts
apps/ec-service/src/capabilities/availability-snapshot-service.ts
apps/ec-service/src/capabilities/activation-service.ts
```
### Why
Without Core owning these transitions, the learning system becomes a bag of traces and drafts instead of a governed capability pipeline.
---
## 3.2 DOC2 — Freshness Manager
### Add
- freshness for:
- observation-derived proposals
- proposal support docs
- installed ability availability snapshots
- connector-backed learned abilities
- stale-badge logic for learned abilities using live or indexed dependencies
### New schema
```ts
import { z } from "zod";
export const LearnedAbilityFreshnessSchema = z.object({
ability_id: z.string().max(160),
freshness_kind: z.enum(["static", "live_dependency", "indexed_dependency", "unknown"]),
verified_as_of: z.string().datetime().optional(),
stale: z.boolean().default(false),
stale_reason: z.string().max(240).optional(),
schema_version: z.literal(1),
});
```
### Why
A learned skill that depends on stale support packs or a dead connector should not be presented as fully healthy.
---
## 3.3 DOC4 — OpenClaw Bridge / EC bridge
### Add bridge routes
```http
POST /api/learn/session/start
POST /api/learn/session/pause
POST /api/learn/session/resume
POST /api/learn/session/stop
POST /api/learn/session/cancel
GET /api/learn/session/:id
POST /api/learn/session/:id/mark-goal
POST /api/learn/session/:id/mark-step
POST /api/learn/session/:id/trim
POST /api/learn/session/:id/generate-proposal
GET /api/learn/proposals
GET /api/learn/proposals/:id
POST /api/learn/proposals/:id/questions
POST /api/learn/proposals/:id/answers
POST /api/learn/proposals/:id/test
POST /api/learn/proposals/:id/install-private
POST /api/learn/proposals/:id/approve
POST /api/learn/proposals/:id/reject
POST /api/learn/proposals/:id/revise
GET /api/learn/receipts
GET /api/abilities/availability
POST /api/abilities/:id/activate
POST /api/abilities/:id/deactivate
POST /api/abilities/:id/quarantine
POST /api/abilities/:id/promote-shared
```
### Add bridge rules
- `elnor-ec` remains the bridge for learning lifecycle state, not just skills/connectors generally
- bridge must carry `LearningQueryContextPayload`
- bridge must not strip proposal/session IDs
### Why
Without these routes, Q can’t actually drive the learning lifecycle.
---
## 3.4 DOC7 — Context Buckets
### Add
- support-pack dependency declarations for learned abilities
- project-binding references usable by Learn sessions
- observation/manual references as optional teaching aids
- “do not store raw captured event streams as ordinary bucket content” rule
### New schema
```ts
import { z } from "zod";
export const LearningSupportDependencySchema = z.object({
proposal_id: z.string().uuid(),
support_pack_id: z.string().max(120),
required: z.boolean().default(true),
reason: z.string().max(240).optional(),
schema_version: z.literal(1),
});
```
### Why
Support packs may be needed to generate or improve a skill, but they are not the same thing as the skill.
---
## 3.5 DOC8 — Self-Learning / Friction
### Add
- LearnSession-aware clustering
- proposal suppression logic
- observation noise metrics
- later-use failure feedback
- “learned skill not found at runtime” as a friction class
- “proposal succeeded but never reused” as a learning-quality signal
### New friction classes
```ts
export const LearnFrictionClassSchema = z.enum([
"observation_noise",
"boundary_misdetected",
"semantic_label_ambiguous",
"proposal_not_routable",
"ability_not_found_at_runtime",
"learned_skill_unused",
]);
```
### Why
A learning system that cannot notice when its output is not reusable will quietly degrade into clutter.
---
## 3.6 DOC9 — Self-Repair Pipeline
### Add
- repair bundles for:
- bad learn-session boundaries
- ambiguous labeling
- broken activation
- degraded installed-private skills
- proposal-to-install failures
- rollback from installed-private to pending/review
- re-draft path from quarantined skill to proposal state
### Why
Learned skills will inevitably break, and the repair system must understand that lifecycle specifically.
---
## 3.7 DOC10 — Unified Engagement Orchestration
### Add
- **Ability Availability Snapshot** as a required consumed read model
- route lookup path for:
- approved/shared abilities
- experimental/private abilities
- task templates
- connector-backed capabilities
- route awareness of learning state
- “use learned ability later” lookup rule
### New artifacts
```text
ELNOR_MEMORY/system/orchestration/ability_availability_current.json
ELNOR_MEMORY/system/orchestration/learning_receipts.jsonl
```
### Suggested schema to consume
```ts
import { z } from "zod";
export const AbilityAvailabilityOverlaySchema = z.object({
ability_id: z.string().max(160),
install_lane: z.enum(["pending", "experimental_private", "approved_workspace", "shared_promoted", "quarantined"]),
usable_now: z.boolean(),
reason_unusable: z.string().max(240).optional(),
trigger_phrases: z.array(z.string().max(200)).default([]),
preferred_routes: z.array(z.string().max(120)).default([]),
schema_version: z.literal(1),
});
```
### Why
This is the missing bridge between “learned it” and “can use it later.”
---
## 3.8 DOC11 — Runtime truth / Gateway / model controls
### Add runtime truth for
- observation adapter availability
- current learn mode availability
- install lane loadability
- ability usability in the current runtime
- bridge/registry freshness for learned abilities
### New runtime fields
```ts
import { z } from "zod";
export const RuntimeLearningTruthSchema = z.object({
observation_supported: z.boolean().default(false),
supported_adapter_kinds: z.array(z.string().max(80)).default([]),
can_install_private: z.boolean().default(false),
can_promote_shared: z.boolean().default(false),
ability_snapshot_fresh: z.boolean().default(false),
schema_version: z.literal(1),
});
```
### Why
If runtime truth does not know whether learned abilities are actually usable, the UI will lie.
---
## 3.9 DOC12 — Inter-Agent Communication / Rooms
### Add
- room-scoped LearnSession links
- proposal pinning state
- active learning target pinning
- room events for:
- session started
- proposal drafted
- questions requested
- installed private
- approved
- quarantined
### New event names
- `learn.session.started`
- `learn.session.cancelled`
- `learn.proposal.created`
- `learn.proposal.questions_requested`
- `learn.proposal.tests_passed`
- `learn.proposal.installed_private`
- `learn.proposal.approved`
- `learn.proposal.quarantined`
### Why
Long review/learning sessions need continuity, especially in rooms.
---
## 3.10 DOC15 — CIL / scoring / payloads
### Add
- `LearningQueryContextPayload` as a deep-link payload pattern
- learning usefulness metrics
- post-install adoption scoring
- receipt and route correlation for learned ability usage
- proposal pinning and active-target continuity patterns reused from the current payload/deep-link philosophy
### New payloads/signals
- `learn_session`
- `skill_bundle_proposal`
- `installed_private_ability`
- `learned_ability_used`
- `learned_ability_rejected`
- `proposal_reopened`
- `proposal_pinned_review_target`
### Why
Learning objects need the same deep-linking and explanation infrastructure as other complex review flows.
---
## 3.11 Q Core / Q UI
### Add
- Learn home/dashboard
- Learn session overlay or global controls
- Recent run picker
- Observation banner
- Proposal review drawer
- Questions panel
- Timeline trim/review UI
- Experimental/private learned abilities list
- Learning receipts feed
- Ability availability panel
- Activation controls
### Required UI states
- idle
- armed
- capturing
- paused
- stopped
- reviewing
- awaiting_questions
- testing
- ready_for_review
- installing_private
- installed_private
- approved
- rejected
- cancelled
- quarantined
- partial_deployment
### Required actions
- start
- pause
- resume
- stop
- cancel
- mark step
- mark goal
- trim
- generate proposal
- answer questions
- test
- install privately
- approve
- reject
- revise
- quarantine
- unquarantine
- activate
- deactivate
### Why
DOC3 can define semantics, but Q must make them real.
---
## 4. Shared code implementation guidance
### 4.1 Packages to create first
```text
packages/contracts/src/learning/*
packages/contracts/src/capabilities/availability-snapshot.ts
packages/contracts/src/capabilities/activation.ts
packages/contracts/src/workflows/workflow-graph.ts
```
### 4.2 EC modules to add
```text
apps/ec-service/src/learning/session-service.ts
apps/ec-service/src/learning/state-machine.ts
apps/ec-service/src/learning/observation-adapters/browser.ts
apps/ec-service/src/learning/observation-adapters/accessibility.ts
apps/ec-service/src/learning/observation-adapters/shortcut.ts
apps/ec-service/src/learning/observation-adapters/midi.ts
apps/ec-service/src/learning/observation-adapters/process.ts
apps/ec-service/src/learning/trace-normalizer.ts
apps/ec-service/src/learning/cluster-service.ts
apps/ec-service/src/learning/clarification-service.ts
apps/ec-service/src/learning/proposal-builder.ts
apps/ec-service/src/learning/test-runner.ts
apps/ec-service/src/learning/install-service.ts
apps/ec-service/src/learning/receipt-writer.ts
apps/ec-service/src/capabilities/ability-availability-snapshot.ts
apps/ec-service/src/capabilities/ability-lookup.ts
apps/ec-service/src/capabilities/install-lane-filter.ts
apps/ec-service/src/capabilities/activation-service.ts
```
### 4.3 Frontend modules to add
```text
apps/q-frontend/src/features/learn/LearnHomePage.tsx
apps/q-frontend/src/features/learn/LearnSessionOverlay.tsx
apps/q-frontend/src/features/learn/LearnSessionTimeline.tsx
apps/q-frontend/src/features/learn/RecentRunPicker.tsx
apps/q-frontend/src/features/learn/ObservationModeBanner.tsx
apps/q-frontend/src/features/learn/ProposalReviewDrawer.tsx
apps/q-frontend/src/features/learn/LearningQuestionsPanel.tsx
apps/q-frontend/src/features/learn/ExperimentalLearnedAbilitiesView.tsx
apps/q-frontend/src/features/learn/LearningReceiptsFeed.tsx
apps/q-frontend/src/features/abilities/AbilityAvailabilityPanel.tsx
apps/q-frontend/src/features/abilities/AbilityActivationControls.tsx
```
### 4.4 Partial deployment rules
If companion docs ship later than DOC3:
- Learn surfaces show `partial_deployment`
- install/promote actions fail closed
- observation mode unavailable if adapters/runtime truth absent
- ability lookup not trusted if availability snapshot missing
- UI must explain what is missing
---
## 5. Recommended implementation sequencing
### Phase A — contracts and lifecycle
- shared learning contracts
- LearnSession state machine
- routes
- receipts
### Phase B — UI shells + proposal lifecycle
- Learn home
- overlay
- review drawer
- question panel
- receipts feed
### Phase C — ability later-use chain
- availability snapshot
- activation/deactivation
- route lookup
- DOC10 awareness
### Phase D — observation adapters
- browser
- shortcut
- accessibility
- process
- optional MIDI
### Phase E — hardening
- repair
- scoring
- DOC15 usefulness
- long-session pinning / deep-link continuity
---
## 6. Final rule
When there is a conflict:
1. shared learning contracts win,
2. EC owns canonical learning state,
3. DOC11 owns runtime truth,
4. DOC10 owns ability awareness consumption and route selection,
5. DOC3 defines learning semantics and packaging,
6. Q makes it visible and actionable,
7. DOC15 supplies deep-link explanation and learning quality scoring,
8. DOC12 preserves continuity of active learning targets.
---
> LEGACY / NON-OPERATIVE: the preserved merged body below is retained for lineage and traceability. Implement from the authoritative R11.2 / R9.2 Part 0 sections above, not from the preserved historical text below.
# Part 4 — Merged Addendum — Retrieval Provider / LlamaIndex / MCP Pack Impacts
# Companion Addendum — Retrieval Provider / LlamaIndex / MCP Pack Impacts
## Purpose
This addendum records the remaining companion-document impacts from:
- DOC3 LlamaIndex Integration Additions R1
- ELNOR First-Wave MCP Pack R3
to ensure the consolidated companion delta fully captures cross-doc changes required by the canonical DOC3.
## 1. DOC10 — Capability awareness / route explanation
### Add
- awareness/read-model support for:
- `llamaindex_index`
- provider-specific connector families from the first-wave MCP pack
- route reason codes for exact vs semantic vs cross-corpus retrieval
- experimental/private vs approved ability visibility
- “why this route” explanation surfaces for:
- Microsoft live search
- Microsoft retrieval/chunk search
- LlamaIndex sidecar retrieval
- QMD/internal semantic retrieval
- local/OpenClaw fallback
- ability cards and read models must surface:
- `retrieval_corpus_hints`
- `connector_server_ids`
- `bundle/collection` membership if relevant
- `install_lane`
- `source` (`learned`, `imported`, `openclaw`, `connector`, `generated`)
### Required rule
DOC10 does not own retrieval/provider truth, but it must **consume and explain it honestly**.
## 2. DOC11 — Runtime truth / provider availability
### Add
- provider/runtime capability truth for:
- OpenAI / Anthropic / Codex / OpenClaw connector availability
- LlamaIndex sidecar health and usable-now status
- MCP family health by provider/server
- browser/local fallback availability
- route suppression when:
- provider denied by policy
- connector unhealthy
- sidecar unavailable
- corpus stale beyond allowed policy
### Required runtime view
- current provider supports MCP? yes/no
- current provider allowed for server family? yes/no
- sidecar healthy? yes/no
- local fallback available? yes/no
## 3. DOC7 — Context Buckets / support packs / project bindings
### Add
- `retrieval_corpus_binding` references for corpora tied to projects/matters
- support-pack relations to LlamaIndex corpora and Microsoft search families
- optional category/collection metadata references for saved skills/tasks/abilities if Q/Core chooses to store those outside pure UI state
### Rule
Project/matter identity remains Core/DOC7 owned; retrieval corpora are projections/bindings, not a rival project model.
## 4. DOC2 — Freshness
### Add
- freshness metadata for:
- Microsoft live retrieval
- sidecar indexed corpora
- stale corpus warnings
- source-of-truth “live vs indexed” distinctions
- UI/state support for “indexed as of” vs “live as of”
## 5. DOC8 — Friction / learning signals
### Add
- route-learning friction classes for:
- Microsoft live route failed but LlamaIndex succeeded
- LlamaIndex stale corpus
- wrong retrieval route chosen
- connector policy denied
- provider mismatch
- candidate learning improvements based on route results and user corrections
## 6. DOC9 — Repair
### Add
- repair proposals for:
- stale LlamaIndex corpora
- bad corpus bindings
- incorrect route preference
- connector family misconfiguration
- MCP provider policy mismatch
- bundle/category browser misclassification if needed
## 7. ELNOR Core / EC
### Add
- corpus-binding management
- route preference learning storage
- provider policy persistence
- connector inventory projection
- collection/category assignment persistence if that is not kept purely in Q state
- unified retrieval orchestration service that can compare:
- live Microsoft
- LlamaIndex
- QMD
- local/OpenClaw
- browser fallback
## 8. Q UI / Actions & Abilities UX
### Add
- Abilities > Connectors page must show first-wave connector families and their state
- Abilities > Skills page must show source families and collection/category assignment
- right-click “Add to Category…” for skills/tasks/automations/learn proposals
- search/browser filters for:
- source
- app/system
- collection/category
- provider
- install lane
- active/experimental/shared state
- retrieval route receipts and provider badges in result views
## 9. Sequencing / partial deployment
### Required sequence
1. canonical DOC3 merge
2. companion delta merge
3. DOC10/DOC11 read-model/runtime updates
4. Q UI surfaces for Actions/Abilities/Learn and connectors
5. EC route orchestration + learning/runtime updates
6. MCP family + sidecar provider rollouts
### Partial deployment rule
Do not expose route-selection or Learn-entry-point UI that implies unavailable backend actions.