270 lines
8.8 KiB
Markdown
270 lines
8.8 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
simulation_only: true
|
|
not_formal_participant_output: true
|
|
excluded_from_synthesis: true
|
|
```
|
|
|
|
It must not be accepted as:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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:
|
|
|
|
```text
|
|
- 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.
|