drift

현재 HEAD 기준으로 durable, memory, harness 지식 객체의 drift 여부를 판정합니다

무엇을 하는 명령인가

drift는 현재 HEAD 기준으로 인덱싱된 문서, reviewed/promoted memory artifact, reviewed/promoted harness suite가 아직 믿을 만한지 읽기 전용으로 판정합니다. 인프라 진단이나 이력 재생이 아니라, 어떤 지식 객체가 fresh, suspect, stale인지 보여 주는 명령입니다.

언제 쓰는가 / 언제 쓰지 않는가

언제 쓰는가

코드나 문서를 바꾼 뒤 어떤 지식 객체를 다시 검토해야 하는지 알고 싶을 때
query, context pack, memory recall 전에 신뢰도 점검을 먼저 하고 싶을 때
harness suite를 다시 실행하지 않고도 freshness를 확인하고 싶을 때

언제 쓰지 않는가

저장소의 현재 상태를 요약해서 보고 싶을 때. status를 사용하십시오.
실패 원인 진단이 필요할 때. doctor를 사용하십시오.
snapshot semantic history를 보고 싶을 때. log를 사용하십시오.
append-only event ledger를 보고 싶을 때. timeline을 사용하십시오.

기본 구문

pnpm ragit drift [--scope durable|memory|harness|all] \
  [--path <glob>] [--goal <goalId>] \
  [--session <sessionId>] [--max-count <n>] \
  [--view minimal|default|full] \
  [--format text|json|both]

인자와 옵션

--scope durable|memory|harness|all: 어떤 trust layer를 평가할지 고릅니다. all은 v1 집중 범위인 durable docs, reviewed/promoted memory, reviewed/promoted harness suites를 뜻합니다.
--path <glob>: repo-relative path glob으로 결과를 좁힙니다.
--goal <goalId>: memory/harness 항목을 goalId로 필터링합니다.
--session <sessionId>: memory/harness 항목을 sourceSessionId로 필터링합니다.
--max-count <n>: 정렬 후 반환할 drift item 개수를 제한합니다.
--view minimal|default|full: 항목별 상세 투영 수준을 선택합니다.
--format text|json|both: 출력 형식을 선택합니다.
--cwd <path>: 다른 저장소를 대상으로 실행합니다.

입력/출력 계약

v1의 drift는 JSON 입력 payload를 받지 않습니다.
JSON 출력은 항상 overallStatus, counts, filters, baseline, items를 포함합니다.
각 item은 scope, itemType, id, title, status, reasonCodes, affectedPaths, sourceRefs, recommendedActions를 포함합니다.

{
  "overallStatus": "stale",
  "counts": {
    "fresh": 8,
    "suspect": 1,
    "stale": 2
  },
  "filters": {
    "scope": "all",
    "path": null,
    "goalId": null,
    "sessionId": null,
    "maxCount": 20
  },
  "baseline": {
    "headSha": "abc123...",
    "snapshotSha": "abc123...",
    "snapshotCommitSha": "abc123...",
    "reasonCodes": []
  },
  "items": [
    {
      "scope": "memory",
      "itemType": "memoryArtifact",
      "id": "art_session_feedback_123",
      "title": "Keep answers concise",
      "status": "stale",
      "reasonCodes": ["related_path_changed"],
      "affectedPaths": ["docs/auth.adr.md"],
      "sourceRefs": {
        "headSha": "def456...",
        "anchorSha": "abc123...",
        "artifactId": "art_session_feedback_123",
        "goalId": "resume-auth"
      },
      "recommendedActions": ["doc refresh", "artifact review", "memory promote"]
    }
  ]
}

대표 사용 예시

사람용 터미널 예시:

pnpm ragit drift --scope all --view default --format both

harness 중심 점검 예시:

pnpm ragit drift --scope harness --goal validate-auth-refresh --format json

실패/주의 사항

v1의 drift는 구조적 판정만 합니다. 의미 모순 탐지나 LLM judge는 하지 않습니다.
captured session artifact는 first-class drift item이 아닙니다.
raw harness run ledger도 first-class drift item이 아닙니다. materialized failure artifact만 suite freshness에 영향을 줍니다.
recommendedActions는 제안일 뿐이며 자동 수정은 수행하지 않습니다.