8.8 KiB
Knowledge Vault Invocation Policy
1. Purpose
This policy defines how Knowledge Vault invokes reusable capabilities, CCPE participants, local scripts, and external agents.
It is a vault-side operating rule. CCPE defines canonical participants; this file defines how this repository accepts or rejects participant outputs during real knowledge-processing work.
2. Scope
Use this policy when a Knowledge Vault workflow invokes:
- CCPE Agent
- CCPE Skill
- CCPE Runtime node
- native platform agent
- external GPT / Gemini / Claude / manual participant
- local script or code-based processor
3. Run-Specific Records
Run-specific invocation records belong in the work item directory, not in skills/.
Example:
discussions/viewpoint-development/{date}-{topic}/
invocations/
{participant-id}/
agent-invocation-packet.md
prompt-to-send.md
returned-output.md
skill-execution-record.md
run-log.md
The public skills/templates/ directory only stores templates.
4. No-Simulation Rule
The main session may:
- create directories and templates
- prepare invocation packets
- prepare prompt-to-send files
- execute local skills when the procedure is explicit
- run scripts and record their inputs and outputs
- collect real participant outputs
- synthesize results that are backed by records
- ask the user for decisions
The main session must not:
- write a formal Agent output as if a canonical Agent produced it
- write a Skill result without a skill-execution-record
- treat a convenience summary as a participant report
- accept an external participant result without source metadata
- proceed when CCPE rules are insufficient to launch the participant safely
If a required participant cannot be truly invoked, mark the stage:
blocked_waiting_for_participant_output
4.1 Invocation Carrier Rule
An invocation packet is not itself a participant execution. A prompt-to-send file is also not execution until it is actually sent to a real participant or executed by a recorded local Skill run.
Accepted invocation carriers:
codex_thread_participant:
valid_when:
- a separate Codex Thread is created or resumed
- thread_id is recorded
- prompt-to-send or canonical artifact reference is sent to that thread
- returned output is saved with thread metadata
required_for:
- persistent alignment participants such as whole-source-gestalt-reviewer
- any participant that may need user correction and same-context follow-up
agent_subsession_participant:
valid_when:
- agent_id is recorded
- returned output is saved with agent metadata
- the task is one-shot, or the agent can be resumed and that continuity path is recorded
not_sufficient_for:
- persistent Step 0 alignment unless the same agent_id can be resumed after user correction
local_skill_execution:
valid_when:
- the executor reads the canonical Skill artifact
- the execution record names the Skill path and version
- procedure steps, inputs, outputs, and validation checks are recorded
caution:
- if the Skill requires substantial source interpretation, prefer worker/thread execution over main-session execution
external_manual_participant:
valid_when:
- prompt-to-send is actually executed outside this session
- platform, operator note, date, returned output path, and source scope are recorded
main_session_synthesis:
valid_when:
- it only merges, indexes, or checks file-backed returned outputs
- it is labeled as integration, not participant output
Invalid as formal participant output:
- a drafted packet that was never sent
- a prompt that merely references a canonical Skill but was never executed
- a main-session summary written in the participant's voice
- a main-session artifact that lacks a skill-execution-record or returned-output record
To say that a run "used the Skill prompt", the record must show that the canonical artifact was either read during a local Skill execution or supplied to a real participant. Merely designing a prompt around the Skill's purpose is not enough.
4.2 Strict Invocation By Default
Strict invocation is the default for any formal Knowledge Vault workflow that claims to use a CCPE Agent, CCPE Skill, or canonical participant.
The strict rule applies to production runs, test runs, audits, and downstream handoffs:
- every substantive processing stage must have a real participant or Skill execution record
- Step 0 must use a persistent carrier when human correction may be needed
- topic graph synthesis must be backed by a participant output or by a recorded integration over worker returns
- evidence routing, topic docs, and material extraction must be produced by worker/sub-session participants
- main-session bounded extraction is not acceptable as a substitute for a required participant
- blocked states must be recorded instead of substituting main-session output
Main-session work is allowed only for orchestration, packet preparation, file-backed integration, bounded verification, and user-confirmation records.
4.3 Human-Review Language Rule
Any artifact that enters a human confirmation gate must use the source material's primary language as its main working language unless the user explicitly requests another language.
This applies to:
- Step 0 whole-source gestalt returned-output.md
- topic-discovery worker returns that require human inspection
- Gate 3 topic graph / hierarchy repair artifacts
- Gate 6 topic docs / material extraction review artifacts
- coverage, distortion, and invocation-validity audits
- downstream routing decisions
- human-confirmation records
Invocation packets and returned outputs must record:
source_primary_language:
output_language_policy: mirror_source_primary_language | user_specified | protocol_default
human_review_language_requirement:
human_confirmation_artifact: true/false
gate_id_if_applicable:
Acceptance rule:
- If an artifact is for human confirmation and its main language does not mirror source_primary_language, do not confirm it.
- Send a repair request to the same persistent participant carrier when available.
- If the carrier cannot be resumed, mark the output language-invalid for formal confirmation and rerun the affected participant.
- Keep technical field names or paths in English where useful, but explanatory content should follow source_primary_language.
4.4 Simulation-Only Material
Simulation is not an invocation mode.
It may be used only when the user explicitly asks for non-formal exploration, such as:
- sketching what a participant packet should contain before the real call
- drafting a disposable comparison sample to understand expected output shape
- diagnosing whether an existing result looks like a real participant output
- creating a simulation-only artifact that is clearly excluded from synthesis
Simulation-only material must be labeled:
simulation_only: true
not_formal_participant_output: true
excluded_from_synthesis: true
It must not be accepted as:
- CCPE Agent output
- CCPE Skill execution
- Runtime participant return
- topic map authority
- routing authority
- material extraction authority
- audit evidence that a participant was invoked
In CCPE-backed workflows, a run can have useful simulation-only analysis and still have no valid participant output for the affected stage.
5. Acceptance Rule
A participant output may be accepted only when at least one condition is true:
- a completed participant startup packet returned a real output
- a prompt-to-send file was executed externally and the returned output was saved
- a local Skill execution record identifies procedure, inputs, outputs, and validation
- a local script record identifies command, inputs, outputs, and validation
- the user explicitly labels material as simulation-only and it is excluded from formal synthesis
6. Insufficient Rule Handling
If CCPE provides an Agent, Skill, Runtime, or protocol that is not specific enough to run safely, Knowledge Vault must pause before formal processing.
Record:
- missing rule or unclear boundary
- affected participant
- blocked output files
- proposed clarification needed
- user decision required
7. External Participant Metadata
Returned external outputs must record:
- participant name
- platform or tool
- date
- prompt-to-send path
- source input range
- returned output path
- operator note, if manually pasted back
8. Local Script Or Code-Based Capability
Some Knowledge Vault capabilities may be implemented as scripts rather than CCPE participants.
The run record must include:
- script path
- command or entrypoint
- input files
- output files
- validation checks
- known limitations
Script output is not an Agent judgment. It must be labeled as deterministic or tool-assisted processing.