# v1.13 Specification Design Memo (Implementation Complete)
Release Date: 2026-02-01
## Position
- This document is a reference for the **specification design phase**.
- Describes "design intent and policies" paired with `templates/code-intel/phase_contract.yml`.
- **Implementation is complete** (v1.13 specifications are reflected).
## Purpose
- Prevent orchestrator → LLM instructions from becoming a black box
- Clarify "instruction content", "referenced auxiliary resources", and "expected return structure" per phase
- Design **context compression** centered on DOCUMENT_RESEARCH
## Common Design Policies (v1.13)
1) Instruction Clarification
- Concretize "what to do" at each phase, eliminating ambiguous instructions
2) Auxiliary Resource Presentation
- **Always present** `.code-intel/*` to reference at each phase
3) Tool Usage Enforcement (No audit logging required)
- Specify required tools in instruction
- Add `tools_used` to `expected_payload` to **submit usage evidence**
- Server-side **verification of tool usage** (reject if unused)
- However, **phases returning only summary** (READY completion / MERGE) don't require `tools_used`
4) Return Minimization + Persistence
- `expected_payload` is **minimal** (phase completion signal + required fields + summary)
- Detailed info **compressed into summary**, **only summary field** persisted
- **Persistence target is summary only (+ orchestrator state)**, other fields not saved
5) Context Compression
- DOCUMENT_RESEARCH extracts → Main reads only necessary parts → Summary/key points persisted
6) Phase Instruction Externalization (phase_contract.yml)
- Aggregate phase instructions (instruction/expected_payload/tools, etc.) in `.code-intel/phase_contract.yml`
- Generally not expected to be modified by users, **only instruction wording adjustments** anticipated if changes occur
- Implementation uses "file-first → fallback to default if undefined" policy
---
## Phase-by-Phase Specification Design (Reflected Instruction Drafts)
### Step 2: BRANCH_INTERVENTION
- Purpose: User selection for stale branch handling
- Instruction policy: **Explain 3 choices with meaning** and have user select
- Instruction format draft (revised):
```json
{
"phase": "BRANCH_INTERVENTION",
"step": 2,
"instruction": "llm_task_* branches detected. Present the following choices to user and send selection via submit_phase. 1) delete: Discard all llm_task_* branches (complete multi-branch discard) 2) merge: Merge only current branch to base, discard others 3) continue: Stay on current branch, don't create new task branch in READY. Explain the meaning of each choice before having user select.",
"expected_payload": {
"choice": "str: 'delete' | 'merge' | 'continue'",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Implementation diff (reflected):
- merge means "merge only current llm_task_* branch → delete". Others are deleted
- continue means "fix to current branch" proceeding to READY
- Required/Recommended tools:
- Required: `submit_phase`
### Step 3: DOCUMENT_RESEARCH
- Purpose: Extract only necessary parts for **context compression**
- Auxiliary resources:
- `.code-intel/context.yml` (project_rules / doc_research / document_search)
- `.code-intel/doc_research/*.md`
- Instruction policy:
- Sub-agent extracts **rule_refs / must_read**
- Main **must read must_read** → Persist summary
- Minimize payload (documents_reviewed + summary + tools_used)
- Instruction format draft (revised):
```json
{
"phase": "DOCUMENT_RESEARCH",
"step": 3,
"instruction": "Based on project_rules in context.yml, investigate design documents following doc_research and document_search. Request investigation from sub-agent, returning primarily rule_refs / must_read. Main agent must read returned must_read, summarize, understand necessary rules/constraints, then send via submit_phase.",
"expected_payload": {
"documents_reviewed": "list[str]",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Persistence (example):
- `rule_refs` / `must_read` / `dependencies` / `warnings` **included as key points in summary** and saved
- Required/Recommended tools:
- Required: `submit_phase`
- Recommended: `search_files` / `search_text`
### Step 4: QUERY_FRAME
- Purpose: Structure instructions (quote verification for hallucination prevention)
- Instruction policy: Slot definition + quote required
- Instruction format draft (revised):
```json
{
"phase": "QUERY_FRAME",
"step": 4,
"instruction": "Decompose user instruction into the following slots, verifying each with original text quote. target_feature (what to target), trigger_condition (occurrence conditions), observed_issue (current problem), desired_action (desired response). Leave unknown slots empty, don't guess. Send via submit_phase when complete.",
"expected_payload": {
"action_type": "str",
"target_symbols": "list[str]",
"scope": "str",
"constraints": "str",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
### Step 5: EXPLORATION
- Purpose: Evidence-based exploration
- Required tools: **2+ types** like `search_text`
- Instruction format draft (revised):
```json
{
"phase": "EXPLORATION",
"step": 5,
"instruction": "Explore using at least 2 types of code-intel tools, summarize exploration rationale in findings, send via submit_phase. List tool names used in tools_used.",
"expected_payload": {
"explored_files": "list[str]",
"findings": "list[str]",
"tools_used": "list[str] (at least 2 types)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: 2+ types like `search_text` / `submit_phase`
- Recommended: `search_files` / `find_definitions` / `get_symbols` / `analyze_structure` / `get_function_at_line` / `find_references`
### Step 6: Q1
- Purpose: Evaluate SEMANTIC necessity
- Instruction format draft (revised):
```json
{
"phase": "Q1",
"step": 6,
"instruction": "Evaluate whether SEMANTIC phase (ChromaDB semantic search: semantic_search) is needed, send with reason via submit_phase. If needed, briefly note what you want to confirm with semantic search.",
"expected_payload": {
"needs_more_information": "bool",
"reason": "str",
"tools_used": "list[str] (empty allowed)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
### Step 7: SEMANTIC
- Required tools: `semantic_search`
- Instruction format draft (revised):
```json
{
"phase": "SEMANTIC",
"step": 7,
"instruction": "Create search query from QueryFrame/EXPLORATION content, gather additional info with semantic_search. Be mindful of map/forest, minimize forest exploration when sufficient confidence from map. Use fetch_chunk_detail as needed, send results via submit_phase.",
"expected_payload": {
"search_query": "str",
"search_results": "list[str]",
"tools_used": "list[str] (must include semantic_search)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `semantic_search` / `submit_phase`
- Recommended: `fetch_chunk_detail`
### Step 8: Q2
- Purpose: Evaluate VERIFICATION necessity
- Instruction format draft (revised):
```json
{
"phase": "Q2",
"step": 8,
"instruction": "VERIFICATION means backing up hypotheses and exploration results (evidence confirmation, contradiction resolution). Judge as needed if there are unverified hypotheses / weak evidence / conflicting results, send with reason via submit_phase.",
"expected_payload": {
"has_unverified_hypotheses": "bool",
"reason": "str",
"tools_used": "list[str] (empty allowed)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
### Step 9: VERIFICATION
- Purpose: Hypothesis verification (evidence required)
- Instruction format draft (revised):
```json
{
"phase": "VERIFICATION",
"step": 9,
"instruction": "Verify hypotheses one by one, show evidence as file:line or tool output. No guessing. If no evidence, set result=false with reason. For code-related hypotheses, always use code-intel tools, list in tools_used.",
"expected_payload": {
"hypotheses_verified": "list[{hypothesis, result, evidence}]",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
- Recommended: `search_text` / `find_definitions` / `find_references`
### Step 10: Q3
- Purpose: Evaluate IMPACT_ANALYSIS necessity
- Instruction format draft (revised):
```json
{
"phase": "Q3",
"step": 10,
"instruction": "Evaluate whether sufficient investigation has been done on impact to references and dependencies of modification points, send with reason via submit_phase.",
"expected_payload": {
"needs_impact_analysis": "bool",
"reason": "str",
"tools_used": "list[str] (empty allowed)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
### Step 11: IMPACT_ANALYSIS
- Required tools: `analyze_impact`
- Instruction format draft (revised):
```json
{
"phase": "IMPACT_ANALYSIS",
"step": 11,
"instruction": "Execute analyze_impact, briefly summarize impact on references/dependencies of modification points, propagation to related files/tests/configs, send via submit_phase.",
"expected_payload": {
"impact_summary": "dict",
"tools_used": "list[str] (must include analyze_impact)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `analyze_impact` / `submit_phase`
### Step 12: READY (Planning)
- Instruction policy:
- Read `.code-intel/task_planning.md` before task division
- Create task list following guidelines
- Instruction format draft (revised):
```json
{
"phase": "READY",
"step": 12,
"instruction": "If .code-intel/task_planning.md exists, read it, create task list following guidelines, send via submit_phase.",
"expected_payload": {
"tasks": "list[{id, description, status, failure_count?, revert_reason?}]",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Note:
- `status` initial value is **"pending"**
- `failure_count` / `revert_reason` **omitted** at this point (server adds)
- Auxiliary resources (original design):
- `.code-intel/task_planning.md` (task division guidelines)
- Required/Recommended tools:
- Required: `submit_phase`
### Step 13: READY (Implementation)
- Instruction policy:
- **Run `check_write_target` first** for change target files
- `submit_phase` after implementation
- Instruction format draft (revised):
```json
{
"phase": "READY",
"step": 13,
"instruction": "Run check_write_target on change target files first, report via submit_phase after implementation.",
"expected_payload": {
"task_id": "str",
"summary": "str (key points needed for resumption)",
"tools_used": "list[str]"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `check_write_target` / `submit_phase`
### Step 14: READY (Completion)
- Instruction policy: Notify all tasks complete
- Instruction format draft (revised):
```json
{
"phase": "READY",
"step": 14,
"instruction": "All tasks complete. Send with summary via submit_phase.",
"expected_payload": {
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Note:
- Step 14 is the **final checkpoint** for "all tasks complete", consolidating incomplete task recheck and branching conditions (no-verify/quick, etc.)
- Even if tasks are added/revised during implementation, final consistency is confirmed here
- Required/Recommended tools:
- Required: `submit_phase`
### Step 15: POST_IMPL_VERIFY
- Instruction policy:
- Select verifier based on change content
- Read `.code-intel/verifiers/*.md`, execute verification
- Instruction format draft (revised):
```json
{
"phase": "POST_IMPL_VERIFY",
"step": 15,
"instruction": "Select appropriate verifier from .code-intel/verifiers/*.md including user-added verifiers, execute verification following procedures. Specify verifier name/path used, describe specific failure content on failure, send via submit_phase.",
"expected_payload": {
"verifier_used": "str (name or path)",
"passed": "bool",
"failed_tasks": "list[str] (if passed=false)",
"details": "str",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Note:
- Transition to Step 16: VERIFY_INTERVENTION if failure continues **3 times**
- Auxiliary resources (original design):
- `.code-intel/verifiers/*.md` (verification procedure presentation)
- Corresponds to old flow Step 8.5
- Required/Recommended tools:
- Required: `submit_phase`
### Step 16: VERIFY_INTERVENTION
- Position:
- Intervention phase triggered when Step 15 failure continues **3 times**
- Instruction policy:
- Reference `.code-intel/interventions/*.md`, select and execute appropriate intervention prompt
- Normally select and execute appropriate prompt from `.code-intel/interventions/*.md`
- Follow `.code-intel/user_escalation.md` **only when orchestrator instructs** (LLM doesn't self-escalate)
- Timing note:
- **Orchestrator issues user_escalation branch** when intervention has been performed **2 times**
- Instruction patterns (2 types):
- Normal intervention (when orchestrator hasn't instructed user_escalation)
- user_escalation instruction (when orchestrator instructs user_escalation)
- Instruction format draft (revised):
```json
{
"phase": "VERIFY_INTERVENTION",
"step": 16,
"instruction": "Step 15 verification failed 3 times, performing intervention. Select and execute appropriate intervention prompt from .code-intel/interventions/*.md, specify prompt name/path used, send via submit_phase.",
"expected_payload": {
"prompt_used": "str (name or path)",
"action_taken": "str",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Instruction format draft (user_escalation instruction):
```json
{
"phase": "VERIFY_INTERVENTION",
"step": 16,
"instruction": "Follow .code-intel/user_escalation.md procedures to request help from user. Specify procedure document name/path used, send via submit_phase.",
"expected_payload": {
"prompt_used": "str (name or path, should be .code-intel/user_escalation.md)",
"action_taken": "str",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Auxiliary resources (original design):
- `.code-intel/interventions/*.md` (intervention for breaking verification loop)
- `.code-intel/user_escalation.md` (last resort: request help from user **only when orchestrator instructs**)
- Required/Recommended tools:
- Required: `submit_phase`
### Step 17: PRE_COMMIT
- Instruction policy:
- Execute `review_changes`
- Follow `garbage_detection.md` to **judge garbage (unnecessary items)**
- Instruction format draft (revised):
```json
{
"phase": "PRE_COMMIT",
"step": 17,
"instruction": "Get diff list with review_changes, judge whether items are garbage (unnecessary) following .code-intel/review_prompts/garbage_detection.md. Specify procedure document name/path used, send results via submit_phase.",
"expected_payload": {
"review_prompt_used": "str (name or path)",
"reviewed_files": "list[str]",
"commit_message": "str",
"tools_used": "list[str] (must include review_changes)",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Auxiliary resources (original design):
- `.code-intel/review_prompts/garbage_detection.md` (garbage detection)
- Required/Recommended tools:
- Required: `review_changes` / `submit_phase`
### Step 18: QUALITY_REVIEW
- Instruction policy:
- Follow `quality_review.md` checklist to evaluate **diff quality**
- Instruction format draft (revised):
```json
{
"phase": "QUALITY_REVIEW",
"step": 18,
"instruction": "Perform quality review following .code-intel/review_prompts/quality_review.md checklist. Specify procedure document name/path used, send results via submit_phase.",
"expected_payload": {
"quality_prompt_used": "str (name or path)",
"quality_score": "str",
"issues": "list[str]",
"tools_used": "list[str]",
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Transition note:
- Revert to READY (Planning) on failure (issues exist)
- **Forced completion** progresses to MERGE when failure count reaches limit
- Auxiliary resources (original design):
- `.code-intel/review_prompts/quality_review.md` (final quality check)
- Corresponds to old flow Step 9.5
- Required/Recommended tools:
- Required: `submit_phase`
### Step 19: MERGE
- Instruction policy: Call submit_phase with summary
- Instruction format draft (revised):
```json
{
"phase": "MERGE",
"step": 19,
"instruction": "Send with summary via submit_phase to execute merge.",
"expected_payload": {
"summary": "str (key points needed for resumption)"
},
"call": "submit_phase"
}
```
- Required/Recommended tools:
- Required: `submit_phase`
---
## Persistence for Checkpoint Recovery (Per Phase)
To make v1.12 checkpoint recovery effective, separately persist **state orchestrator should maintain** and **context LLM should re-read on resumption**.
(Save location example: `.code-intel/sessions/{session_id}.json` / summary can also link with context.yml)
### A) State Orchestrator Should Maintain (LLM generally doesn't read)
- **Common (all phases)**
- session_id / flags / phase_state
- counters (verification_failure_count / quality_revert_count / intervention_count)
- **compaction_count** (compaction detection counter. Control summary return based on LLM mismatch)
- **Step 2: BRANCH_INTERVENTION**
- branch_policy (usually null. Maintained as "fix to current branch" intent only when continue selected)
- **Step 12: READY (Planning)**
- tasks (id/description/status/failure_count/revert_reason)
- ※Step 12 tasks **extracted from submit payload and saved** (no duplicate generation)
- **Others**
- No additional storage needed (can be recovered if only summary is saved to phase_payloads)
### B) Context LLM Should Re-read on Resumption (LLM-facing summary)
- **Policy**: Don't retain original raw context. Allow **compression to summary** on resumption, keeping only key points of decisions, constraints, and unresolved issues.
- **Guideline**: Focus on important points only. Bullet points should be **5 items or fewer**, text should have **200-400 character upper limit**, re-compress if exceeded.
- **Handling**: Don't enumerate specific items, **include summary in each phase's submit payload, persist only summary**.
- **Note**: Summary length is a **guideline**, not strictly enforced server-side.
---
## Persistence Granularity and Specific Storage Structure
### 1) Granularity (Principle)
- Save **only minimal info needed for resumption** (avoid verbose full text)
- **References for reproducibility** prefer `path:line`
- **Don't save heavy content (long text/large diff/full logs)**
- If needed, keep only "summary" + "reference"
### 2) Storage Location (Draft)
- **Session state**: `.code-intel/sessions/{session_id}.json`
- State needed for resumption, minimal summary
- **Summary auxiliary** (optional): `.code-intel/context.yml`
- project_rules / doc_research update summary
### 3) File Structure (Draft)
- **Note**: `phase_payloads` shown here is an **excerpt example**, actual contains all phases that returned summary.
- **Note**: `phase_payloads` key naming is not fixed (`step_XX_*` is an example).
```json
{
"orchestrator_state": {
"session_id": "20260201_123456",
"flags": {
"no_verify": false,
"no_quality": false,
"fast": false,
"quick": false,
"no_doc": false,
"no_intervention": false
},
"phase_state": {
"current_phase": "EXPLORATION",
"step": 5,
"ready_substep": null
},
"branch_policy": "continue",
"counters": {
"verification_failure_count": 0,
"quality_revert_count": 0,
"intervention_count": 0
},
"compaction_count": 0,
"tasks": [
{ "id": "T1", "description": "Fix login", "status": "pending", "failure_count": 0 }
]
},
"phase_payloads": {
"step_02_BRANCH_INTERVENTION": {
"summary": "Selected merge current branch only"
},
"step_03_DOCUMENT_RESEARCH": {
"summary": "Brief summary of key points"
},
"step_12_READY_PLANNING": {
"summary": "Key points of plan"
},
"step_14_READY_COMPLETION": {
"summary": "Confirmed all tasks complete"
},
"step_19_MERGE": {
"summary": "Merge executed"
}
}
}
```
### 4) Operational Rules (Draft)
- **phase_state is required**
- **orchestrator_state is authoritative for control values** (phase_payloads summary is summary/auxiliary)
- **artifacts can be empty** (unexecuted phases can be missing)
- **phase_payloads saves only summary** (other fields discarded)
- **Counters are not reset on session resumption** (inherited persisted values, reset follows existing implementation timing)
- Set JSON **size limit** (e.g., 256KB)
- If exceeded, **re-compress summary**, keep only `path:line` references if needed
## Compaction Resilience: compaction_count Method
### Issue
v1.13 implemented mechanism to persist submit payload `summary` to `phase_payloads`, but **path to return persisted summaries to LLM was undefined**.
- `get_session_status` doesn't return `phase_payloads`
- No guarantee LLM calls `get_session_status` after compaction
- Boolean `recovered` flag **cannot detect second+ compactions**
### Design: compaction_count Counter Method
**Principle**: Server and LLM share `compaction_count` (integer), detect compaction by **value mismatch**.
#### Flow
1. Session start: Server-side `compaction_count = 0`
2. Normal submit: LLM sends `compaction_count: 0` → Server `0` matches → Normal response
3. **First compaction occurs**: LLM detects "continued from previous conversation" header → submit with `compaction_count: 1`
4. Server: Held value `0` ≠ received value `1` → **Mismatch detected** → Attach summaries to response + update held value to `1`
5. Normal submit: LLM sends `compaction_count: 1` → Server `1` matches → Normal response
6. **Second compaction occurs**: LLM re-detects continuation header → Based on previous response `compaction_count: 1`, `+1` → submit with `compaction_count: 2`
7. Server: Held value `1` ≠ received value `2` → **Mismatch detected** → Attach summaries to response + update held value to `2`
#### Server Implementation Requirements
1. **Add `compaction_count: int = 0` to SessionState**
- Persist/restore in `to_dict()` / `to_compact_dict()` / `from_dict()`
2. **Always include `compaction_count` in submit_phase response**
- So LLM can reference this value and `+1` after compaction
3. **Detect `compaction_count` mismatch in submit_phase**
- When `data.get("compaction_count")` differs from `session.compaction_count`:
- Attach all summaries from `phase_payloads` as `phase_summaries` in response
- Update `session.compaction_count` to received value
4. **Include `compaction_count` in get_session_status**
- To be referenceable on `-r` skill recovery
#### LLM Protocol (Auto-attached to all instructions via get_phase_response)
1. **Include `compaction_count` in data for every submit_phase**
- **Normal**: Echo back `compaction_count` from previous submit_phase response
- **Right after compaction**: If previous submit_phase response not in context, send `last known compaction_count + 1` (send `1` if unknown)
- **2+ turns after recovery**: Previous response available → Echo back (don't +1)
- **Note**: Trigger is **availability of previous response**, not "continued from previous conversation" header. Header remains on all turns after compaction, header-based check would +1 every time.
2. **Read `phase_summaries` if included in response**
- Reference summaries to restore context up to previous phases
- Next time returns to normal submit (summaries returned only once)
#### Recovery via `-r` Skill
- When session recovery via `-r`, LLM starts with `compaction_count: 0`
- Will necessarily mismatch with `compaction_count` held server-side → Summaries returned
- Result: Summary recovery occurs via same path as new compaction
#### phase_summaries Response Format
```json
{
"success": true,
"phase": "Q1",
"step": 6,
"instruction": "...",
"expected_payload": { ... },
"compaction_count": 1,
"phase_summaries": {
"step_02_BRANCH_INTERVENTION": "Selected merge current branch only",
"step_03_DOCUMENT_RESEARCH": "Brief summary of key points",
"step_05_EXPLORATION": "Exploration results summary"
}
}
```
- `phase_summaries` is flattened dict of just `summary` values from `phase_payloads`
- `phase_summaries` key itself not included in response during normal operation (no mismatch)
---
## Implementation Reflected (v1.13)
- Added `tools_used` / `summary` to `expected_payload` (READY completion / MERGE have summary only)
- Server-side **required tool usage verification** (payload_mismatch if unused)
- Server-side **summary presence verification** (READY completion / MERGE also require summary)
- BRANCH_INTERVENTION merge/continue behavior fix
- **Only summary** from submit payload persisted to `phase_payloads`
- phase_contract.yml loading support (instruction/expected_payload overwrite possible)
- `.code-intel/phase_contract.yml` actual file generation
- **compaction_count method for compaction resilience** (summary return path to LLM)
