/apt-stSemanticTwin — crystallization of AtomicSpans into Contract + Task.
/apt-st Claude Code CLI 또는 연결된 에이전트에서 호출합니다.
> **ST = Verify & Correct 축.** > Contract는 APT 품질의 유일한 병목. 모호한 Contract → 모호한 코드. 정밀한 Contract → 검증 가능한 코드. > SemanticTwin = Contract(DTO) + SemanticTask(TDD 완료조건)의 결합체.
> `apt-gate-check.sh`가 자동 실행. SP Gate 미통과 시 `permissionDecision: deny`. > `$PROJECT`는 apt-progress.md의 `## Anchor:` 에서 읽는다. > BLOCKED 시: `/apt-sp` → `/taliban` → SP Gate 통과 → `/apt-st` 재호출. ---
### 1. Crystallization Frontier — SP↔ST 유일한 관문 SP에서 **모든** leaf가 AtomicSpan(C(S) 5-predicate 통과)이 된 후에만 ST 진입. 개별 Span이 먼저 ST로 빠지지 않음 — **전체 DAG의 모든 leaf가 Atomic이면 그때 전환.** SP는 Contract를 직접 소유하지 않는다. ### 2. 전체를 펼쳐놓고 — 개별이 아닌 집합 > "개별 span이 아닌 **전체 Atomic span 집합**을 한꺼번에 보며 > span 간 데이터 흐름, 의존성, SharedType을 고려한 일관된 Contract 생성" 이것이 ST가 SP와 다른 핵심. SP는 하향식 분해, ST는 **수평적 전체 조감**. ### 3. Contract = Typed DTO/Schema (NOT prose) | Field | Type | 설명 | |-------|------|------| | `input_type` | typed | gRPC protobuf, function signature, dataclass | | `output_type` | typed | 반환 타입. 추상(data, any, result) **금지** | | `precondition` | predicate | 입력 조건. 실행 가능한 assertion | | `postcondition` | predicate | 출력 보장. 실행 가능한 assertion | | `acceptance_criteria` | test spec | 통과/실패 판정 기준 | | `semantic_meaning
### Step 1: AtomicSpan 전체 로드
```cypher
MATCH (sa:SemanticAnchor {name: $PROJECT})-[:HAS_ROOT]->(root)
MATCH (root)-[:DECOMPOSES_TO*1..10]->(atom:AtomicSpan)
WHERE atom.is_atomic = true
RETURN atom.name, atom.description, atom.target_file, atom.estimated_lines
ORDER BY atom.name
```
### Step 2: SharedType 식별
전체 AtomicSpan을 보며 **공통 데이터 구조**를 찾는다:
- 여러 Span이 같은 입력/출력 타입을 공유하는가?
- 병렬 Task 사이를 흐르는 DTO가 있는가?
- 공통 인터페이스가 있는가?
→ 식별된 SharedType = **별도 Contract 노드**로 생성.
### Step 3: 개별 Contract 생성 (7대 필드)
각 AtomicSpan에 대해:
```cypher
MATCH (atom:AtomicSpan {name: $ATOM})
MERGE (st:SemanticTwin {name: 'ST_' + $ATOM})
MERGE (c:AptContract {name: 'CONTRACT_' + $ATOM})
SET c.input_type = $INPUT_TYPE, // 구체적 typed
c.output_type = $OUTPUT_TYPE, // 추상 타입 금지
c.precondition = $PRECONDITION,
``` Draft → [7 fields + review] → Active → [FulfillmentGate] → Fulfilled → Archived ``` - **Draft**: 필드 작성 중 - **Active**: 7대 필드 완성, 리뷰 통과 - **Fulfilled**: SCW에서 Task PASS - **Archived**: 프로젝트 완료 또는 폐기 ---
### 보존 - 전체 Contract 목록 (7대 필드) - SemanticTask 목록 (acceptance_criteria) - SharedType 관계 - SEQUENCED_WITH 실행 순서 ### 제거 - Contract 초안 히스토리 - SharedType 탐색 과정 ---
| 금지 | 이유 | 대안 | |------|------|------| | 추상 타입 (data, any, result) | 검증 불가 | 구체적 typed interface | | 개별 Span에 1:1 Contract | SharedType 누락 | 전체를 펼쳐놓고 공유 타입 식별 | | precondition/postcondition이 prose | 테스트 불가 | assertion으로 작성 | | SP에서 바로 Contract | Crystallization Frontier 위반 | 모든 leaf Atomic 후 ST 진입 | | Contract를 코드에서 유추 | KG가 정본 | KG에 먼저 기록, 코드는 물질화 | | target_file 미지정 | 롱기누스 추적 불가 | 반드시 물질화 경로 명시 |