diff --git a/skills/context-management-policy.md b/skills/context-management-policy.md index 236733b..21fb138 100644 --- a/skills/context-management-policy.md +++ b/skills/context-management-policy.md @@ -20,6 +20,18 @@ The main session is responsible for: - user confirmation gates ``` +For coherent long sources that fit a high-context participant, Knowledge Vault should first run a real whole-source gestalt sub-session before range splitting. This does not relax the main-session rule: the main session prepares the invocation, records the returned output, and uses the gestalt as orientation. + +The whole-source gestalt sub-session is responsible for: + +```text +- reading the full source when it fits the agreed high-context limit +- judging whether the source is one coherent topic or should be split into macro-topics +- producing the global topic portrait, main structure, core tensions, and model-evolution line +- flagging parent/child/tool/case/action-layer distinctions that range workers may flatten +- giving segmentation guidance for downstream workers +``` + Worker sessions are responsible for: ```text @@ -34,6 +46,7 @@ Worker sessions are responsible for: Use this sequence: ```text +0. Run or record an exception to the whole-source gestalt pass. 1. Split by Markdown H1 round. 2. If a round is too large, split by H2 section. 3. If a section is still too large, split by source block batch. @@ -46,6 +59,8 @@ Use worker threads when a processing pass needs to read large source ranges or p Each worker thread should receive a thread-start packet and return a thread-return packet. +Worker thread-start packets should include the accepted whole-source gestalt summary when it exists. Workers may challenge that global portrait, but must label the challenge and cite local evidence. + Run-specific packet paths: ```text diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/capability-spec.md b/skills/knowledge-processing/viewpoint-discussion-distillation/capability-spec.md index e4b72df..1deb7e3 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/capability-spec.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/capability-spec.md @@ -38,14 +38,18 @@ First preserve, then structure. The source material layer must remain separate from the structured viewpoint layer. Topic documents may reorganize ideas, but must keep source block ids and enough original material to support later reuse. +For coherent discussion sources that fit a high-context participant, first get a whole-source gestalt judgment before segmentation. The global portrait prevents chunk-first workers from flattening tools, layers, cases, action tracks, and model upgrades into false peer topics. + ## 5. Human Gates ```text Gate 1: Confirm workspace path. Gate 2: Confirm source block convention. -Gate 3: Confirm candidate topic-map. -Gate 4: Confirm audit repair strategy. -Gate 5: Confirm downstream routing. +Gate 3: Confirm whole-source gestalt use or recorded exception. +Gate 4: Confirm candidate topic-map / topic hierarchy. +Gate 5: Confirm material routing. +Gate 6: Confirm audit repair strategy. +Gate 7: Confirm downstream routing. ``` ## 6. Acceptance Criteria diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-runtime-alignment.md b/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-runtime-alignment.md index 5b6971b..f3017b7 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-runtime-alignment.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-runtime-alignment.md @@ -11,6 +11,12 @@ C:\Users\wangq\Documents\Codex\ccpe-system\skills\workflow\conversation-segmenta C:\Users\wangq\Documents\Codex\ccpe-system\skills\workflow\evidence-routing-and-topic-doc-builder.skill.md ``` +Pending sync request: + +```text +CCPE should add a whole-source-gestalt-reviewer participant and update the viewpoint-discussion-distillation Runtime from a chunk-first flow to a 9-step flow with Step 0 Whole-Source Gestalt Pass. +``` + ## 2. Responsibility Split ```text diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-sync-request-2026-06-06-whole-source-gestalt.md b/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-sync-request-2026-06-06-whole-source-gestalt.md new file mode 100644 index 0000000..806f542 --- /dev/null +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-sync-request-2026-06-06-whole-source-gestalt.md @@ -0,0 +1,98 @@ +# CCPE Sync Request: Whole-Source Gestalt Pass + +## 1. Background + +Knowledge Vault discovered a structural weakness in the current `viewpoint-discussion-distillation` flow. + +The previous flow was too `chunk-first / worker-first`: + +```text +source registration -> segmentation -> worker topic extraction -> synthesis -> routing +``` + +This works for loose, very long, multi-topic material, but it is risky for coherent discussion drafts under the high-context limit. Range workers see local evidence and can lose the global shape. The failure mode is that tools, layers, cases, action tracks, and model-upgrade relations get flattened into peer topics. + +## 2. Required Runtime Change + +Upgrade the Runtime to a 9-step operational flow by adding Step 0: + +```text +0. Whole-Source Gestalt Pass +1. Segmentation +2. Worker Topic Extraction +3. Topic Graph Synthesis +4. Human Structure Confirmation +5. Material Routing +6. Topic Docs +7. Coverage / Distortion Audit +8. Downstream Task Routing +``` + +Knowledge Vault still needs source registration before this operational flow so it can create the workspace, source map, run notes, and invocation records. If CCPE keeps source registration inside the canonical Runtime, the practical order should be: + +```text +registration -> Step 0 whole-source gestalt -> segmentation -> worker passes +``` + +## 3. New Participant Needed + +Add a canonical participant: + +```text +participant_id: whole-source-gestalt-reviewer +participant_type: high_context_participant +runtime: viewpoint-discussion-distillation +invocation_mode: real sub-session only +main_session_may_simulate: false +``` + +The main session must not perform this pass itself. It prepares the invocation packet, records the returned output, and uses it as orientation for downstream segmentation and worker extraction. + +## 4. Output Contract + +The participant output should include: + +```text +- participant identity and invocation metadata +- source document path and source version note +- coherence judgment: coherent / mixed / fragmented +- coherence rationale and split recommendation if mixed or fragmented +- global topic portrait +- main structure or candidate layers +- core tensions and governing questions +- model-evolution line +- parent/child/tool/case/action-layer distinctions +- chunk-first distortion risks +- segmentation guidance for downstream workers +- confidence notes and unresolved structure questions +``` + +This output is not a final topic map, material routing log, or coverage audit. It is an upstream global orientation layer. + +## 5. Worker Rule Change + +Worker participants should no longer discover the global structure from zero when a whole-source gestalt output exists. + +They should: + +```text +- receive the accepted gestalt summary in their thread-start packet +- extract local evidence, refinements, contradictions, and exceptions +- explicitly mark any challenge to the global portrait +- cite local source ranges for every challenge +``` + +## 6. Knowledge Vault Side Already Updated + +Knowledge Vault updated these public capability files: + +```text +skills/context-management-policy.md +skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md +skills/knowledge-processing/viewpoint-discussion-distillation/context-strategy.md +skills/knowledge-processing/viewpoint-discussion-distillation/invocation-contract.md +skills/knowledge-processing/viewpoint-discussion-distillation/participant-registry.md +skills/knowledge-processing/viewpoint-discussion-distillation/ccpe-runtime-alignment.md +``` + +CCPE should synchronize the canonical Runtime, participant registry, and any agent/skill specs needed to make `whole-source-gestalt-reviewer` invocable as a real participant. diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/context-strategy.md b/skills/knowledge-processing/viewpoint-discussion-distillation/context-strategy.md index 2e4eeaa..8dced5f 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/context-strategy.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/context-strategy.md @@ -2,17 +2,38 @@ ## 1. Default Strategy -The orchestrator should not process the full source in one context. +The main orchestrator should not process the full source in one context. Use: ```text main session -> source registration and orchestration +whole-source gestalt reviewer -> full-source high-context structure review worker thread -> bounded range processing file handoff -> durable cross-session state ``` -## 2. Range Order +The whole-source gestalt reviewer is a real sub-session participant, not the main session. It exists to preserve the overall shape of coherent long discussions before range workers begin. + +## 2. Whole-Source Gestalt Rule + +For coherent discussion drafts that fit inside a high-context participant, run a whole-source gestalt pass before segmentation. + +The pass must judge: + +```text +- whether the source is one coherent topic or several loosely related topics +- the global topic portrait +- the main structural layers +- core tensions and governing questions +- model-evolution lines +- likely parent/child/tool/case/action-layer distinctions +- risks that chunk-first workers may flatten into false peer topics +``` + +If the source is too large or not coherent enough for one gestalt pass, record the exception and use a small number of macro-range gestalt passes before worker segmentation. + +## 3. Range Order ```text 1. H1 rounds: R01, R02, R03 @@ -20,7 +41,7 @@ file handoff -> durable cross-session state 3. source block batches when a section is too large ``` -## 3. Worker Input +## 4. Worker Input Each worker gets: @@ -28,12 +49,15 @@ Each worker gets: - thread-start packet - participant invocation packet - exact source range +- accepted whole-source gestalt summary or recorded exception - output path - forbidden actions - return packet template ``` -## 4. Worker Output +Workers should use the gestalt summary as orientation. They may challenge it with local evidence, but they must explicitly mark the challenge and cite the source range. + +## 5. Worker Output Each worker writes: @@ -44,10 +68,12 @@ Each worker writes: - unresolved issue list, if needed ``` -## 5. Main Session Reading Rule +## 6. Main Session Reading Rule The main session reads worker summaries and indexes first. It reads source excerpts only for verification or repair. -## 6. Continuation Rule +The main session may read the accepted whole-source gestalt output because it is a participant result with a record. It must not replace that result with its own informal full-source judgment. + +## 7. Continuation Rule Create a continuation handoff after each major pass or before any expected context pressure. diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/invocation-contract.md b/skills/knowledge-processing/viewpoint-discussion-distillation/invocation-contract.md index 78837c8..579bba2 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/invocation-contract.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/invocation-contract.md @@ -16,9 +16,14 @@ model_mining_required: optional no_simulation_requirement: true human_confirmation_required_before: - final_topic_map + - material_routing - source_disposable_claim - writing_workbench_handoff - downstream_task_routing +whole_source_gestalt_required_when: + - source_is_coherent + - source_fits_high_context_participant +whole_source_gestalt_exception_requires_record: true ``` ## 2. Run Directory Contract @@ -41,6 +46,7 @@ human_confirmation_required_before: ```text invocations/ + whole-source-gestalt-reviewer/ conversation-segmentation/ topic-discovery-router/ evidence-routing-and-topic-doc-builder/ @@ -54,7 +60,28 @@ conversation-segmentation/R01/ conversation-segmentation/R02/ ``` -## 4. Blocked State +## 4. Whole-Source Gestalt Output Contract + +`whole-source-gestalt-reviewer/returned-output.md` must include: + +```text +- participant identity and invocation metadata +- source document path and source version note +- coherence judgment: coherent / mixed / fragmented +- coherence rationale and split recommendation if mixed or fragmented +- global topic portrait +- main structure or candidate layers +- core tensions and governing questions +- model-evolution line +- parent/child/tool/case/action-layer distinctions +- chunk-first distortion risks +- segmentation guidance for downstream workers +- confidence notes and unresolved structure questions +``` + +This output is orientation and constraint material. It is not a substitute for source block indexing, evidence routing, or coverage audit. + +## 5. Blocked State Use this state when the run cannot accept a participant output: diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/participant-registry.md b/skills/knowledge-processing/viewpoint-discussion-distillation/participant-registry.md index 7607445..c525590 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/participant-registry.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/participant-registry.md @@ -1,5 +1,16 @@ # Participant Registry +## whole-source-gestalt-reviewer + +- participant_type: high_context_participant +- canonical_artifact_path: pending_ccpe_sync +- default_invocation_mode: prompt_path_reference or full_prompt_paste in a real sub-session +- required_record: `agent-invocation-packet.md` +- external_record_when_needed: `prompt-to-send.md` plus returned output +- output_kind: whole-source topic portrait and coherence judgment +- must_run_before: `conversation-segmentation` when the source is coherent and within the high-context whole-source limit +- must_not_be_simulated_by_main_session: true + ## conversation-segmentation - participant_type: ccpe_skill diff --git a/skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md b/skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md index 756431a..2744145 100644 --- a/skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md +++ b/skills/knowledge-processing/viewpoint-discussion-distillation/runbook.md @@ -7,10 +7,11 @@ 2. Read this capability folder. 3. Read CCPE runtime handoff and invocation protocol. 4. Confirm target work directory with the user. -5. Confirm whether the first pass stops after source registration or proceeds to segmentation. +5. Confirm whether the source is likely under the high-context whole-source limit. +6. Confirm whether the first pass stops after source registration or proceeds to whole-source gestalt. ``` -## 2. First Pass +## 2. First Pass: Source Registration ```text 1. Create the confirmed work directory. @@ -18,32 +19,68 @@ 3. Write README.md. 4. Write 00-source-map.md with source metadata and round boundaries. 5. Write 03-run-notes.md with decisions and gates. -6. Create invocation records for the first participant. +6. Create invocation records for the whole-source gestalt reviewer when applicable. 7. Stop at the agreed confirmation point. ``` -## 3. Segmentation Pass +## 3. Step 0: Whole-Source Gestalt Pass + +Use this pass before segmentation when the source is one coherent discussion and can fit inside a high-context participant. + +```text +1. Prepare a whole-source-gestalt-reviewer invocation packet. +2. Invoke a real high-context participant in a sub-session; the main session must not perform this pass itself. +3. The participant reads the full source and first judges topic coherence. +4. If the source is coherent, output a global topic portrait, main structure, core tensions, model-evolution line, and hierarchy risks. +5. If the source is not coherent, output a split recommendation before any topic extraction. +6. Save returned-output.md with source metadata and participant metadata. +7. Write or update 03-run-notes.md with the accepted gestalt output path. +8. Stop if no real participant output is available. +``` + +Acceptance condition: + +```text +Segmentation and worker topic extraction may proceed only after the run has either: +- an accepted whole-source gestalt output; or +- a recorded exception explaining why the source cannot or should not receive a whole-source pass. +``` + +## 4. Segmentation Pass ```text 1. Create worker thread-start packets by source range. -2. Execute or dispatch conversation-segmentation. -3. Write skill-execution-record.md for local execution. -4. Collect source block indexes and worker return packets. -5. Create a continuation handoff before topic discovery. +2. Include the accepted whole-source gestalt summary and hierarchy cautions in each worker packet. +3. Execute or dispatch conversation-segmentation. +4. Write skill-execution-record.md for local execution. +5. Collect source block indexes and worker return packets. +6. Create a continuation handoff before topic discovery. ``` -## 4. Topic Discovery Pass +## 5. Topic Discovery Pass ```text 1. Prepare topic-discovery-router invocation packet. -2. Prepare prompt-to-send.md if the participant is external. -3. Stop if real invocation is unavailable. -4. Save returned output with metadata. -5. Draft 01-topic-map.md from accepted returned output. -6. Pause for user confirmation. +2. Provide the whole-source gestalt output as binding context, not as a final topic map. +3. Instruct workers to supplement and challenge the global portrait with local evidence, not rediscover the whole structure from zero. +4. Prepare prompt-to-send.md if the participant is external. +5. Stop if real invocation is unavailable. +6. Save returned output with metadata. +7. Draft 01-topic-map.md from accepted returned output. +8. Pause for user confirmation. ``` -## 5. Routing And Topic Docs +## 6. Topic Graph Synthesis And Human Confirmation + +```text +1. Convert flat topic candidates into a topic hierarchy or graph. +2. Preserve distinctions among parent topic, subtopic, tool, layer, case, action track, and model upgrade. +3. Compare the synthesized hierarchy against the whole-source gestalt output. +4. Record unresolved hierarchy risks before routing. +5. Pause for user confirmation before material routing. +``` + +## 7. Routing And Topic Docs ```text 1. Confirm topic-map. @@ -53,7 +90,7 @@ 5. Do not declare completion until coverage audit is accepted. ``` -## 6. Audit +## 8. Audit ```text 1. Prepare lossless-coverage-auditor invocation packet. @@ -63,7 +100,7 @@ 5. Ask user before any source-disposable claim. ``` -## 7. Downstream Handoff +## 9. Downstream Handoff Create downstream packets only after user confirmation.