473 lines
15 KiB
Markdown
473 lines
15 KiB
Markdown
---
|
|
artifact_type: refactor-plan
|
|
name: viewpoint-gestalt-first-runtime-refactor-plan
|
|
author: CCPE System
|
|
created: 2026-06-07
|
|
status: draft-plan
|
|
classification: hybrid-artifact
|
|
primary_form: CCPE-Runtime refactor plan
|
|
secondary_components:
|
|
- CCPE-Agent creation plan
|
|
- CCPE-Skill update plan
|
|
- CCPE-Runtime subprotocol update plan
|
|
source_handoffs:
|
|
- workbench/analysis/viewpoint-runtime-agent-refactor-handoff-2026-06-07.md
|
|
- C:/Users/wangq/Documents/Codex/knowledge-vault/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-sync-request-2026-06-06-whole-source-gestalt.md
|
|
target_runtime: runtimes/hybrid/viewpoint-discussion-distillation.runtime.md
|
|
---
|
|
|
|
# Viewpoint Gestalt-First Runtime Refactor Plan
|
|
|
|
## 1. Classification
|
|
|
|
```text
|
|
Primary Classification:
|
|
CCPE-Runtime refactor
|
|
|
|
Secondary Components:
|
|
- CCPE-Agent specs
|
|
- CCPE-Skill specs
|
|
- Runtime subprotocol
|
|
- Human confirmation gates
|
|
- Invocation validity rules
|
|
|
|
Usage Mode:
|
|
Hybrid Mode
|
|
|
|
Depth vs Automation Orientation:
|
|
Hybrid, with depth-oriented structure judgment and automation-supported file/routing work
|
|
```
|
|
|
|
This is not a Knowledge Vault material-routing task. It is a CCPE canonical artifact synchronization task.
|
|
|
|
## 2. Goal
|
|
|
|
Upgrade `viewpoint-discussion-distillation` from a chunk-first / worker-first flow into a gestalt-first topic graph workflow.
|
|
|
|
The refactor should make the following canonical:
|
|
|
|
```text
|
|
- full-source structural alignment before segmentation when feasible
|
|
- real participant invocation for every substantive stage
|
|
- persistent carrier requirement for Step 0 when user correction may be needed
|
|
- topic graph synthesis as a formal participant boundary
|
|
- hierarchy repair before material routing
|
|
- material-unit extraction records before topic-doc confirmation
|
|
- invocation validity audit before coverage success claims
|
|
```
|
|
|
|
## 3. Current File Difference Check
|
|
|
|
### 3.1 Runtime
|
|
|
|
File:
|
|
|
|
```text
|
|
runtimes/hybrid/viewpoint-discussion-distillation.runtime.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.1 draft.
|
|
- Runtime currently has 6 stages:
|
|
1. source registration
|
|
2. segmentation
|
|
3. topic discovery
|
|
4. material routing and topic doc building
|
|
5. coverage and distortion audit
|
|
6. downstream task routing
|
|
- Runtime already has a general no-simulation rule.
|
|
- Runtime already requires invocation packet / returned output / Skill execution record for formal participant output.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Add Preflight: Source Registration, or keep source registration as a pre-operational step.
|
|
- Add Step 0: Whole-Source Gestalt Alignment.
|
|
- Add Gate 0: Human confirmation of gestalt lens before worker extraction.
|
|
- Add topic-discovery workers as lens-guided local extraction, not zero-based global discovery.
|
|
- Add topic-graph-synthesizer as a formal participant boundary.
|
|
- Add explicit Hierarchy Repair Pass before material routing.
|
|
- Add hard rule: no 02-material-routing-log.md until hierarchy repair / structure confirmation is accepted.
|
|
- Add evidence routing / topic docs / material extraction as worker or sub-session work.
|
|
- Add Gate 6: Topic docs and extraction usefulness confirmation.
|
|
- Add coverage audit requirement for invocation validity, not only source coverage.
|
|
- Add strict invocation as default for production, tests, audits, and downstream handoffs.
|
|
```
|
|
|
|
### 3.2 Agent Invocation Packet Protocol
|
|
|
|
File:
|
|
|
|
```text
|
|
runtimes/hybrid/agent-invocation-packet.protocol.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.2.0 draft.
|
|
- Defines invocation modes:
|
|
full_prompt_paste
|
|
prompt_path_reference
|
|
native_agent_id
|
|
local_skill_execution
|
|
manual_handoff
|
|
- Defines real participant test.
|
|
- Defines no-simulation rule.
|
|
- Defines skill-execution-record.md format.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Add carrier metadata:
|
|
carrier_type
|
|
thread_id
|
|
agent_id
|
|
persistent_required
|
|
resume_or_followup_method
|
|
execution_status
|
|
strict_invocation_required
|
|
simulation_only
|
|
- Add returned-output.md as required evidence for participant output.
|
|
- Add explicit acceptance rule:
|
|
packet-only is not execution
|
|
prompt-to-send-only is not execution
|
|
canonical artifact path reference is not enough unless the participant can read it and the record proves it did
|
|
- Add persistent carrier rule for Step 0 when human correction may be needed.
|
|
- Add default strict invocation profile for production, tests, audits, and downstream handoffs.
|
|
- Add distinction between main_session_synthesis and formal participant judgment.
|
|
```
|
|
|
|
### 3.3 Topic Discovery Router Agent
|
|
|
|
File:
|
|
|
|
```text
|
|
agents/agent-specs/topic-discovery-router.agent.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.1 draft.
|
|
- Already talks about topic graph and routing judgment.
|
|
- Still treats discovery, routing, and downstream candidate judgment as one broad role.
|
|
- Does not explicitly receive a confirmed Whole-Source Gestalt lens.
|
|
- Does not explicitly require challenges to the lens to cite source ranges.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Re-scope from global topic discoverer to lens-guided local discovery / challenge router.
|
|
- In coherent-source mode, receive confirmed Step 0 lens and source excerpt packs.
|
|
- Extract local evidence, refinements, contradictions, exceptions, and downstream candidates.
|
|
- Explicitly mark challenges to the Step 0 lens with source block IDs or source ranges.
|
|
- Stop owning final topic graph synthesis; hand that boundary to topic-graph-synthesizer.
|
|
- Output parent-child candidates, layer membership, model/tool/action/example distinctions, and merge/split candidates.
|
|
```
|
|
|
|
### 3.4 Conversation Segmentation Skill
|
|
|
|
File:
|
|
|
|
```text
|
|
skills/workflow/conversation-segmentation.skill.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.1 draft.
|
|
- Correctly defines segmentation as non-interpretive.
|
|
- Requires Skill execution record when executed locally.
|
|
- Does not mention Step 0 lens path or worker packet handling.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Preserve non-interpretive segmentation rule.
|
|
- Add optional accepted_gestalt_lens_path / lens_id in input contract.
|
|
- Clarify that segmentation may include lens references in downstream worker packets but must not classify topics.
|
|
- Require source-map to record whether segmentation happened before or after Step 0.
|
|
- Keep source block IDs stable for downstream challenge citations.
|
|
```
|
|
|
|
### 3.5 Evidence Routing And Topic Doc Builder Skill
|
|
|
|
File:
|
|
|
|
```text
|
|
skills/workflow/evidence-routing-and-topic-doc-builder.skill.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.1 draft.
|
|
- Requires source material layer and source block IDs.
|
|
- Requires Skill execution record when executed locally.
|
|
- Does not yet require material-unit extraction records.
|
|
- Does not explicitly require worker/sub-session execution for source-heavy extraction.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Require confirmed topic graph before formal routing.
|
|
- Require material-unit extraction records before Gate 6 topic docs confirmation.
|
|
- Treat source-heavy routing and material extraction as worker/sub-session work unless explicitly executed as local Skill with full record.
|
|
- Every material unit must carry source block IDs.
|
|
- Topic docs must separate:
|
|
source material layer
|
|
structured interpretation layer
|
|
downstream task layer
|
|
- Main session may integrate returned outputs only; it must not create formal topic docs by simulation.
|
|
```
|
|
|
|
### 3.6 Lossless Coverage Auditor Agent
|
|
|
|
File:
|
|
|
|
```text
|
|
agents/agent-specs/lossless-coverage-auditor.agent.md
|
|
```
|
|
|
|
Current status:
|
|
|
|
```text
|
|
- Exists.
|
|
- Version is v0.1 draft.
|
|
- Audits source block coverage, source material layer, distortion risk, and downstream readiness.
|
|
- Does not audit invocation validity as a first-class coverage condition.
|
|
- Does not flag missing carrier metadata or missing Skill execution records.
|
|
```
|
|
|
|
Required changes:
|
|
|
|
```text
|
|
- Add invocation validity audit.
|
|
- Flag formal outputs created by main-session simulation.
|
|
- Flag missing carrier metadata, returned-output.md, prompt-to-send return, or Skill execution record.
|
|
- Coverage success cannot be claimed when required participant outputs are missing.
|
|
- Add regression checks for polished output without valid participant records.
|
|
```
|
|
|
|
### 3.7 Missing New Agent Specs
|
|
|
|
Missing files:
|
|
|
|
```text
|
|
agents/agent-specs/whole-source-gestalt-reviewer.agent.md
|
|
agents/agent-specs/topic-graph-synthesizer.agent.md
|
|
```
|
|
|
|
Required creation:
|
|
|
|
```text
|
|
whole-source-gestalt-reviewer:
|
|
High-context participant for Step 0 structural alignment.
|
|
Reads full source when feasible.
|
|
Produces global topic portrait, coherence judgment, model-evolution line, hierarchy risks, and segmentation guidance.
|
|
Must not produce final topic map, evidence routing, topic docs, material extraction, or audit.
|
|
|
|
topic-graph-synthesizer:
|
|
Formal synthesis participant after Step 0 and worker topic extraction.
|
|
Receives confirmed Step 0 lens, worker returns, challenges, exceptions, and user corrections.
|
|
Produces topic hierarchy / graph, parent-child distinctions, tool/layer/case/action distinctions, and unresolved hierarchy risks.
|
|
Must not invent new source interpretation unless invoked with source access as a real participant.
|
|
```
|
|
|
|
## 4. Proposed Canonical Flow
|
|
|
|
Recommended Runtime flow:
|
|
|
|
```text
|
|
Preflight. Source Registration
|
|
Create or confirm workspace, source-map shell, run notes, and invocation record directories.
|
|
|
|
Step 0. Whole-Source Gestalt Alignment
|
|
whole-source-gestalt-reviewer reads the full source when feasible.
|
|
If full source is too long, use 2-3 quasi-global packs and synthesize a global gestalt report.
|
|
|
|
Gate 0. Gestalt Human Confirmation
|
|
User confirms, corrects, rejects, or requests another Step 0 pass.
|
|
|
|
Step 1. Conversation Segmentation
|
|
Segmentation remains source-preserving and non-interpretive.
|
|
|
|
Step 2. Lens-Guided Worker Topic Extraction
|
|
Workers validate, enrich, localize, and challenge the confirmed gestalt lens.
|
|
|
|
Step 3. Topic Graph Synthesis
|
|
topic-graph-synthesizer creates hierarchy, parent-child relations, cross-links, merge/split candidates, and model/tool/action/example distinctions.
|
|
|
|
Gate 3. Structure Confirmation / Hierarchy Repair
|
|
User confirms or repairs the topic graph.
|
|
Material routing is blocked until this gate passes.
|
|
|
|
Step 4. Evidence Routing / Topic Docs / Material Extraction
|
|
evidence-routing-and-topic-doc-builder runs as worker/sub-session work or local Skill execution with full record.
|
|
|
|
Gate 6. Topic Docs And Extraction Usefulness Confirmation
|
|
User checks whether extracted material is useful enough for downstream automation.
|
|
|
|
Step 5. Coverage / Distortion / Invocation Validity Audit
|
|
lossless-coverage-auditor checks source coverage and participant validity.
|
|
|
|
Step 6. Downstream Task Routing
|
|
Only after audit and human confirmation.
|
|
```
|
|
|
|
## 5. File Modification Plan
|
|
|
|
### Batch 1: Runtime And Invocation Backbone
|
|
|
|
Modify:
|
|
|
|
```text
|
|
runtimes/hybrid/viewpoint-discussion-distillation.runtime.md
|
|
runtimes/hybrid/agent-invocation-packet.protocol.md
|
|
```
|
|
|
|
Acceptance criteria:
|
|
|
|
```text
|
|
- Runtime encodes gestalt-first flow.
|
|
- Runtime separates Preflight registration from Step 0.
|
|
- Runtime includes Gate 0, Hierarchy Repair, Gate 6, and strict invocation rules.
|
|
- Invocation protocol includes carrier metadata and returned-output acceptance rules.
|
|
- Packet-only and prompt-to-send-only are explicitly invalid as execution evidence.
|
|
```
|
|
|
|
### Batch 2: New Formal Participants
|
|
|
|
Create:
|
|
|
|
```text
|
|
agents/agent-specs/whole-source-gestalt-reviewer.agent.md
|
|
agents/agent-specs/topic-graph-synthesizer.agent.md
|
|
```
|
|
|
|
Acceptance criteria:
|
|
|
|
```text
|
|
- Whole-Source Gestalt Reviewer is a high-context participant, not a summary Skill.
|
|
- Topic Graph Synthesizer is a formal boundary between worker returns and evidence routing.
|
|
- Both require Agent Invocation Packet records and returned real output.
|
|
- Both include no-simulation and persistent-carrier rules.
|
|
```
|
|
|
|
### Batch 3: Existing Agent / Skill Updates
|
|
|
|
Modify:
|
|
|
|
```text
|
|
agents/agent-specs/topic-discovery-router.agent.md
|
|
skills/workflow/conversation-segmentation.skill.md
|
|
skills/workflow/evidence-routing-and-topic-doc-builder.skill.md
|
|
agents/agent-specs/lossless-coverage-auditor.agent.md
|
|
```
|
|
|
|
Acceptance criteria:
|
|
|
|
```text
|
|
- Topic Discovery Router accepts confirmed Step 0 lens and marks local challenges with source ranges.
|
|
- Conversation Segmentation remains non-interpretive while carrying lens metadata forward.
|
|
- Evidence Routing and Topic Doc Builder requires confirmed topic graph and material-unit records.
|
|
- Lossless Coverage Auditor audits invocation validity and rejects formal synthesis from simulation-only material.
|
|
```
|
|
|
|
### Batch 4: Handoff And Creation Brief Sync
|
|
|
|
Modify only after canonical files are updated:
|
|
|
|
```text
|
|
workbench/analysis/knowledge-vault-viewpoint-runtime-handoff.md
|
|
workbench/analysis/viewpoint-discussion-distillation-creation-brief.md
|
|
```
|
|
|
|
Possible new file:
|
|
|
|
```text
|
|
workbench/analysis/knowledge-vault-viewpoint-runtime-sync-response-2026-06-07.md
|
|
```
|
|
|
|
Acceptance criteria:
|
|
|
|
```text
|
|
- Knowledge Vault receives a concise sync response.
|
|
- Handoff points to updated canonical Runtime, Protocol, Agents, and Skills.
|
|
- It does not claim Knowledge Vault source processing is complete.
|
|
```
|
|
|
|
## 6. Human Decision Points
|
|
|
|
Before editing canonical artifacts, confirm:
|
|
|
|
```text
|
|
1. Use canonical participant id `whole-source-gestalt-reviewer`, not `whole-source-gestalt-reader`.
|
|
2. Treat Source Registration as Runtime Preflight, then Step 0 begins the cognition workflow.
|
|
3. Create `topic-graph-synthesizer.agent.md` as a standalone Agent, not only an unnamed Runtime node.
|
|
4. Add regression checks as spec-level checklists first, not as executable tests.
|
|
5. Update CCPE canonical files first; do not edit Knowledge Vault source-processing files in this pass.
|
|
```
|
|
|
|
Recommended decisions:
|
|
|
|
```text
|
|
1. Yes.
|
|
2. Yes.
|
|
3. Yes.
|
|
4. Yes for this batch.
|
|
5. Yes.
|
|
```
|
|
|
|
## 7. Validation Checklist For The Refactor
|
|
|
|
After implementation, check:
|
|
|
|
```text
|
|
- Runtime has no remaining chunk-first default for coherent sources under high-context limit.
|
|
- Step 0 is explicitly a real participant stage, not main-session reading.
|
|
- Gate 0 requires human confirmation before worker lens binding.
|
|
- Workers can challenge the Step 0 lens with source evidence.
|
|
- Topic graph synthesis is distinct from local worker extraction.
|
|
- Material routing is blocked until topic graph / hierarchy is accepted.
|
|
- Topic docs require material-unit extraction records.
|
|
- Coverage audit includes invocation validity.
|
|
- Simulation-only material is excluded from formal synthesis.
|
|
- Knowledge Vault remains the output workspace for source-derived topic documents.
|
|
```
|
|
|
|
## 8. Next Action
|
|
|
|
If approved, execute Batch 1 first:
|
|
|
|
```text
|
|
1. Update runtimes/hybrid/viewpoint-discussion-distillation.runtime.md.
|
|
2. Update runtimes/hybrid/agent-invocation-packet.protocol.md.
|
|
3. Re-read both files and check for the required flow and strict invocation rules.
|
|
```
|
|
|
|
Do not generate:
|
|
|
|
```text
|
|
- 02-material-routing-log.md
|
|
- topics/*.md
|
|
- coverage audit for the Knowledge source
|
|
- downstream-task-routing
|
|
```
|
|
|
|
Those belong to a future Knowledge Vault run after CCPE canonical rules are updated.
|