15 KiB
15 KiB
| artifact_type | name | author | created | status | classification | primary_form | secondary_components | source_handoffs | target_runtime | |||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| refactor-plan | viewpoint-gestalt-first-runtime-refactor-plan | CCPE System | 2026-06-07 | draft-plan | hybrid-artifact | CCPE-Runtime refactor plan |
|
|
runtimes/hybrid/viewpoint-discussion-distillation.runtime.md |
Viewpoint Gestalt-First Runtime Refactor Plan
1. Classification
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:
- 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:
runtimes/hybrid/viewpoint-discussion-distillation.runtime.md
Current status:
- 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:
- 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:
runtimes/hybrid/agent-invocation-packet.protocol.md
Current status:
- 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:
- 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:
agents/agent-specs/topic-discovery-router.agent.md
Current status:
- 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:
- 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:
skills/workflow/conversation-segmentation.skill.md
Current status:
- 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:
- 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:
skills/workflow/evidence-routing-and-topic-doc-builder.skill.md
Current status:
- 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:
- 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:
agents/agent-specs/lossless-coverage-auditor.agent.md
Current status:
- 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:
- 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:
agents/agent-specs/whole-source-gestalt-reviewer.agent.md
agents/agent-specs/topic-graph-synthesizer.agent.md
Required creation:
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:
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:
runtimes/hybrid/viewpoint-discussion-distillation.runtime.md
runtimes/hybrid/agent-invocation-packet.protocol.md
Acceptance criteria:
- 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:
agents/agent-specs/whole-source-gestalt-reviewer.agent.md
agents/agent-specs/topic-graph-synthesizer.agent.md
Acceptance criteria:
- 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:
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:
- 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:
workbench/analysis/knowledge-vault-viewpoint-runtime-handoff.md
workbench/analysis/viewpoint-discussion-distillation-creation-brief.md
Possible new file:
workbench/analysis/knowledge-vault-viewpoint-runtime-sync-response-2026-06-07.md
Acceptance criteria:
- 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:
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:
1. Yes.
2. Yes.
3. Yes.
4. Yes for this batch.
5. Yes.
7. Validation Checklist For The Refactor
After implementation, check:
- 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:
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:
- 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.