163 lines
5.2 KiB
Markdown
163 lines
5.2 KiB
Markdown
# Invocation Contract
|
|
|
|
## 1. Minimum Runtime Input
|
|
|
|
```yaml
|
|
runtime_id: viewpoint-discussion-distillation
|
|
source_document_path:
|
|
source_type:
|
|
round_boundary_rule:
|
|
intended_use: viewpoint-development
|
|
output_workspace_path:
|
|
source_primary_language:
|
|
human_review_output_language: mirror_source_primary_language
|
|
lossless_requirement: true
|
|
allow_topic_overlap: true
|
|
writing_handoff_required: optional
|
|
model_mining_required: optional
|
|
no_simulation_requirement: true
|
|
strict_invocation_required: true
|
|
main_session_primary_extraction_allowed: false
|
|
human_confirmation_required_before:
|
|
- accepting_whole_source_gestalt_as_worker_lens
|
|
- final_topic_map
|
|
- accepting_topic_docs_for_downstream_use
|
|
- 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
|
|
|
|
```text
|
|
{workspace}/
|
|
README.md
|
|
00-source-map.md
|
|
01-topic-map.md
|
|
02-material-routing-log.md
|
|
03-run-notes.md
|
|
topics/
|
|
audits/
|
|
model-mining/
|
|
handoff/
|
|
invocations/
|
|
```
|
|
|
|
## 3. Invocation Directory Contract
|
|
|
|
```text
|
|
invocations/
|
|
whole-source-gestalt-reviewer/
|
|
conversation-segmentation/
|
|
topic-discovery-router/
|
|
topic-graph-synthesizer/
|
|
evidence-routing-and-topic-doc-builder/
|
|
lossless-coverage-auditor/
|
|
```
|
|
|
|
Subdirectories may be split by range:
|
|
|
|
```text
|
|
conversation-segmentation/R01/
|
|
conversation-segmentation/R02/
|
|
```
|
|
|
|
## 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
|
|
- source primary language and output language policy
|
|
- coherence judgment: coherent / mixed / fragmented
|
|
- coherence rationale and split recommendation if mixed or fragmented
|
|
- recommended downstream mode: structure-first / macro-topic split / flat-discovery
|
|
- 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
|
|
- worker lens recommendation: required / partial / omitted
|
|
- confidence notes and unresolved structure questions
|
|
- human confirmation status: pending / confirmed / needs revision / rejected
|
|
```
|
|
|
|
This output is orientation and constraint material. It is not a substitute for source block indexing, evidence routing, or coverage audit. It becomes a worker structure lens only after human confirmation.
|
|
|
|
Because this output is a Gate 0 human-confirmation artifact, its explanatory content must primarily use `source_primary_language` unless the user requests another language. If the language policy is missing or violated, Gate 0 cannot accept it; repair through the same persistent participant carrier or rerun Step 0.
|
|
|
|
This participant must use a persistent carrier when human correction may be needed:
|
|
|
|
```text
|
|
preferred_carrier: codex_thread_participant
|
|
required_record:
|
|
- thread_id or resumable agent_id
|
|
- initial prompt-to-send path
|
|
- returned-output.md
|
|
- all follow-up correction prompts
|
|
- all follow-up returned outputs
|
|
```
|
|
|
|
If Step 0 was run by a one-shot agent that cannot be resumed, the stage may be kept as a reference analysis result, but it is not a valid Step 0 alignment record for the formal workflow.
|
|
|
|
## 4.1 Topic Graph Synthesis Contract
|
|
|
|
Topic graph synthesis is a substantive stage.
|
|
|
|
It must be backed by one of:
|
|
|
|
```text
|
|
- `topic-graph-synthesizer/returned-output.md` from a real participant
|
|
- a `synthesis-record.md` that only integrates file-backed worker returned outputs and does not add new source interpretation
|
|
```
|
|
|
|
The main session may format and index the graph, but it must not invent hierarchy that is not present in Step 0, worker returns, or user corrections.
|
|
|
|
After the user confirms the candidate topic hierarchy and any unresolved expansion boundaries, material routing is not a separate human-confirmation gate. It is the mechanical implementation of the confirmed topic graph. Pause again only if routing exposes new user-level decisions, such as merge/split conflicts, downstream scope changes, source-disposable claims, or handoff targets.
|
|
|
|
## 5. Topic Docs Human Confirmation Contract
|
|
|
|
After worker-backed topic docs and material extraction are generated, record:
|
|
|
|
```text
|
|
topic_docs_human_confirmation.md
|
|
```
|
|
|
|
It must include:
|
|
|
|
```text
|
|
- confirmation status: confirmed / needs revision / rejected
|
|
- reviewed topic docs or material index
|
|
- source primary language and human-review language used
|
|
- whether extracted materials are useful for downstream work
|
|
- whether another extraction pass is required
|
|
- whether downstream handoff may proceed
|
|
- user corrections, if any
|
|
```
|
|
|
|
Gate 6 is valid only after:
|
|
|
|
```text
|
|
- evidence routing records exist
|
|
- topic-doc drafts or returned outputs exist
|
|
- material-unit extraction records exist
|
|
- any main-session integration is labeled as integration
|
|
```
|
|
|
|
## 6. Blocked State
|
|
|
|
Use this state when the run cannot accept a participant output:
|
|
|
|
```text
|
|
blocked_waiting_for_participant_output
|
|
```
|
|
|
|
Record the reason in `03-run-notes.md` or the relevant invocation directory.
|