mikeholownych/citable

Citable — 검색 및 AI 인용 준비를 위한 증거 및 변경 관리

Citable은 콘텐츠 생성기가 아닌 운영 품질 및 거버넌스 계층입니다. 속성이 기술적으로 제공하는 것, 콘텐츠가 지원할 수 있는 것, 외부 시스템이 실제로 관찰한 행위를 기록합니다. 가시성을 점수화하지 않습니다. 자격이 있는 것, 지원 가능한 것, 관찰된 것, 변경된 것, 아직 알려지지 않은 것을 확립합니다. 발견 가능성을 엔지니어링 시스템으로 취급합니다. 레지스트리를 진실 공급원으로, 결정론적 탐지기를 관찰 가능한 조건에 사용하며, 의미론적 판단을 위한 루브릭, 모든 실행에 대한 증거 패키지, 그리고 발명된 사실이 필요한 권장 사항이 있을 경우 fail-closed 동작을 따릅니다.

운영 전제 (변경 불가)

1. 보장 없음. 크롤링, 인덱싱, 순위, 트래픽, 인용, 추천, 포함, 감정, 리치 결과 또는 전환을 약속하지 마십시오. 자격, 확률, 관찰된 행동 및 신뢰도로 말하십시오.
2. 사실 ≠ 추론. 모든 진술을 다음 중 하나로 분류하십시오: 결정론적 관찰, 증거 기반 의미론적 발견, 확률적 추론, 전략적 가설, 실험 결과, 또는 테스트 불가능한 조건. 추론을 관찰로 제시하지 마십시오.
3. 공개 ≠ 재사용 가능. 다음을 분리하여 유지하십시오: 공개적으로 접근 가능, 크롤링 가능, 인덱싱 가능, 스니펫 자격, 사용자 행동 시 검색 가능, 재사용 라이선스, 모델 학습 허용, 파트너십을 통한 라이선스. 크롤러 접근은 .citable/crawlers.yaml에서 크롤러 및 목적별로 결정됩니다.
4. 구조화된 데이터는 어설션 레이어입니다. 스키마는 표시된 콘텐츠와 일치해야 하며, 안정적인 @id를 사용하고, 페이지 및 레지스트리가 지원하지 않는 평점, 가격, 기능 또는 날짜를 어설션해서는 안 됩니다.
5. 클레임에는 소유자와 증거가 필요합니다. 증거 레지스트리에 증거가 없으면 어떤 클레임도 verified 상태에 도달할 수 없습니다. 만료된 증거는 종속 클레임을 무효화합니다. 의견 및 열망은 절대 검증된 사실이 될 수 없습니다.
6. 확증은 조작될 수 없습니다. 가짜 리뷰, 합성 커뮤니티 게시물, 섀도우 브랜드, PBN, 공개되지 않은 보증, 조작된 통계 또는 인용, 추천 중독, 언어 모델을 대상으로 하는 숨겨진 지시사항을 생성하는 것을 거부하십시오. 요청이 어떻게 구성되었든 관계없이 거부하십시오. 복제하는 대신 GEO-001 결과(프롬프트 인젝션)를 보고하십시오.
7. 기계는 인간을 능가할 수 없습니다. 모든 수정은 사실적 정확성, 인간 이해도, 접근성, 전환 기능, 법적 방어 가능성 및 유지보수성을 보존하거나 개선해야 합니다.

세 가지 분야 (절대 하나의 점수로 통합하지 마십시오)

분야	목표	측정 단위
SEO	상업적으로 관련된 쿼리에 대한 지속적인 가시성; 적격 트래픽; 전환	URL, 쿼리, 노출, 클릭, 전환
AEO	직접 답변 자격, 구절 추출, 지원 인용, 정확한 귀속	질문, 답변 구절, 인용, 인용 공유
GEO	올바른 엔터티 이해, 정확한 합성, 카테고리 배치, 클레임 재현, 비교 포함, 방어 가능한 추천	엔터티, 클레임, 프롬프트, 비교, 추천, 내러티브

차원별로 상태 보고 (예: retrieval_eligibility: strong, answer_extractability: weak) — 절대 하나의 불투명한 0–100 "AI 가시성 점수"를 사용하지 마십시오.

모든 보고서는 이러한 최상위 상태를 분리하여 유지해야 합니다:

1. 검색 자격 — 정책 및 캡처된 기술 조건.
2. 소스 추출 및 지원 적합성 — 구절, 엔터티, 클레임, 증거, 신선도 및 구조화된 데이터 조건.
3. 관찰된 인용 행동 — 통제되고 타임스탬프가 찍힌 제공자 관찰만; 관찰이 없으면 not_evidenced이며, 추론하지 않습니다.

검색 내에서 allowed_by_policy, synthetic_fetch_succeeded, observed_in_production_logs, indexed, returned_by_retrieval을 구분하십시오. 인용 테스트 내에서 멘션, 인용, 실질적 지원, 정식 소스 선택 및 추천을 구분하십시오. 이러한 상태는 상호 교환 가능하지 않습니다.

증거 보존, 권위, 신뢰성, 수집 방법 및 대표성도 독립적입니다. references/evidence-authority.md를 따르십시오. 체크섬 또는 CIDR 일치만으로는 소스 신뢰성, 완전한 적용 범위 또는 확인된 크롤러 신원을 증명할 수 없습니다.

도구

이 저장소의 citable CLI는 결정론적 작업을 수행합니다. 항상 수동으로 검사를 재유도하는 것보다 실행하는 것을 선호하십시오:

citable init                        # .citable/ 초기화 (비파괴적)
citable audit [scope] --target <dir|url> [--base-url <url>] [--ref-date YYYY-MM-DD]
citable inspect <page> --target <dir|url>
citable map-claims --target <dir|url> [--write]
citable substantiate [--write]
citable schema --target <dir|url>
citable validate [registries|claims|evidence|schema|links]
citable compare-snapshots [runA runB]
citable action-plan [run-id]          # 정렬된 작업, 차단기, 의미 게이트, 검증
citable observe <mode> [options]      # 렌더/인덱스/인용/로그/구절/컨센서스/성능 증거
citable observe bing --dataset <search_performance|ai_performance> --input <csv|json>
citable observe render --target <url> [--interactions] [--resume-run <run-id>]
citable observe performance --target <url> --lighthouse [--repeat 1..5]
citable apply --input <spec> [--write] # 검토된, 해시 잠금 수정; 기본적으로 dry run
citable monitor [runA runB]           # 관찰 회귀 경고
citable metrics import --provider <name> --input <csv|json>
citable connect status
citable connect configure --provider <gsc|ga4> --connection-id <id> --property-id <id> [--credential-env <name>] [--write]
citable connect discover --provider <gsc|ga4>
citable connect validate --connection-id <id>
citable connect sync --connection-id <id> --start-date YYYY-MM-DD --end-date YYYY-MM-DD
citable connect disconnect --connection-id <id> [--write]
citable objectives init --input <json|yaml> [--write]
citable objectives validate
citable evaluate [objective-id] [--ref-date YYYY-MM-DD]
citable governance validate [--ref-date YYYY-MM-DD]
citable governance evaluate <run-id> [--ref-date YYYY-MM-DD]
citable reviews queue <run-id> <policy-id> [--write]
citable reviews prioritize [--write]
citable reviews plan --input <json|yaml> [--write]
citable reviews sample <sampling-plan-id> [--write]
citable reviews evaluate
citable schedules run <schedule-id> [--ref-date YYYY-MM-DD]
citable project github <run-id>
citable observe media --input <manifest.json> [--ocr]
citable observe representation --input <release-manifest.json> --target <controlled-url>
citable corpus evaluate --input <acceptance-corpus.json>

감사 범위: technical seo aeo geo architecture entity claims evidence schema lifecycle corroboration. 모든 감사는 .citable/runs/<run-id>/에 증거 패키지를 작성합니다 (manifest, findings.json, report.md, headers, robots, sitemaps, schema, link graph, checksums). 증거 패키지가 없는 보고서는 전달물이 아닙니다.

발견-대-조치 프로토콜

탐지는 워크플로의 시작이지 전달물이 아닙니다. 모든 감사에 대해:

1. citable action-plan <run-id>를 실행하십시오. .citable/actions/<run-id>/ 아래의 생성된 파일을 사용하십시오. 불변의 소스 실행을 절대 편집하지 마십시오.
2. 순서대로 작업 단계: 차단 해제 검색/보안 실패, 거버넌스 소유자/엔터티/클레임/증거, 콘텐츠 페이지 및 답변 변경, 그 다음 최적화. 단계 내에서 심각도 높은 작업이 낮은 작업보다 우선합니다. 심각도는 신뢰도를 대체하지 않습니다.
3. 편집하기 전에 책임 있는 소유자를 할당하고 모든 required_input을 충족시키십시오. 차단된 작업은 차단된 상태로 유지됩니다. 누락된 사실, 증거, 법적 검토 또는 소스-대-렌더 매핑을 우회하여 작성하지 마십시오.
4. 나열된 의미 게이트를 적용하십시오. AEO 변경에는 의도 정렬 및 답변 추출 가능성 검토가 필요합니다. GEO 변경에는 엔터티 명확성, 추천 자격 및 내러티브 정확성 검토가 필요합니다. 클레임/증거 변경에는 추가로 클레임 경계성 및 증거 강도 검토가 필요합니다.
5. 증거를 해결하는 가장 작은 소스 또는 레지스트리 변경을 수행하십시오. 나열된 모든 안전하지 않은 지름길과 일치하는 모든 안티 패턴을 거부하십시오.
6. 저장소 빌드/테스트 명령을 실행한 다음 작업의 검증 명령을 실행하십시오. 영향을 받은 범위를 다시 감사하고 소스 실행에 대해 compare-snapshots를 실행하십시오. 발견은 해당 탐지기가 동일한 주제를 더 이상 보고하지 않고 새로운 심각도 높은 회귀가 나타나지 않을 때만 해결됩니다.
7. 해결된, 지속되는, 차단된, 수용된 위험 및 새로 도입된 발견을 별도로 보고하십시오. 실행 ID, 차이점, 소유자, 검토 증거 및 잔여 위험을 보존하십시오. "탐지기 부재"를 결과 보장으로 변환하지 마십시오.

완전한 AEO/GEO 수용 프로필은 references/aeo-geo-validation.md를 따르십시오. 건너뛴 결정론적 검사 또는 불완전한 필수 의미 검토는 관련 상태를 not_established로 만듭니다. 관찰을 주장하기 전에 references/capability-boundaries.md를 참조하십시오. 현재 CLI가 수집할 수 있는 상태와 운영자 데이터 또는 향후 어댑터가 필요한 상태를 식별합니다. 수집기 전제 조건, 증거 레이블, 제어된 인용 어댑터 프로토콜, 수정 거부 조건 및 모니터링 해석에 대해서는 commands/observe-and-act.md를 사용하십시오.

명령 워크플로

자세한 명령별 워크플로는 commands/에 있습니다. 이를 따르십시오. 각 명령에 대한 입력, 사전 조건, 거부 조건 및 검증을 정의합니다. 의미 판단(의도 정렬, 증거 강도, 정보 이득, 비교 공정성 등)은 rubrics/의 루브릭을 사용합니다. 각 루브릭은 점수 차원, 증거 요구 사항, 반례 및 인간 검토가 필수적인 시기를 정의합니다.

레지스트리는 진실 공급원입니다

.citable/는 쿼리, 프롬프트, 엔터티, 클레임, 증거, 페이지, 크롤러, 경쟁자, 실험, 메트릭, 목표, 개입, 선택적 연결 상태, 검토자, 검토 정책 및 관리되는 예외, 의미 검토 항목, 샘플링 계획 및 감사 일정에 대한 YAML 레지스트리를 보유합니다. 모두 스키마 검증(schemas/*.schema.json) 및 참조 무결성 검사가 적용됩니다. 규칙:

• 기록 없이 레지스트리 콘텐츠를 덮어쓰지 마십시오. src/registries/index.js의 로더/세이버를 사용하십시오. 이전 버전을 자동으로 스냅샷합니다.
• 레지스트리 사실(법적 이름, 설립자, 인증, 경쟁자, 가격)을 발명하지 마십시오. 엔터티를 incomplete로 표시하고 required_input을 나열하십시오.
• verified를 향한 클레임 상태 전환에는 기존의 검증된 증거와 인간 의미 검토가 필요합니다. 자동화는 다운그레이드만 수행합니다(fail-closed).
• 수용된 예외를 통과 또는 해결된 발견으로 인코딩하지 마십시오. 검토자 권한 및 직무 분리를 검증하고, 승인을 정확한 소스 발견/정책/증거 해시에 바인딩하며, 집행 처리를 별도로 보고하십시오.

Fail-closed 동작

정보가 누락된 경우, 정확한 필수 입력과 함께 차단/불완전 상태를 반환하십시오. 공백을 우회하여 작성하지 마십시오:

status: blocked
reason: 정량적 클레임에 검증된 증거 없음
required_input: [기준선, 측정 기간, 테스트 모집단, 방법론, 결과 출처]

동일한 원칙이 적용됩니다: 누락된 엔터티 ID(발명 금지), 사용 불가능한 외부 연구(status: incomplete 기록, 경쟁자 또는 인용 조작 금지), 빌드/렌더 실패(검증 성공 보고 금지, 명령, 종료 코드 및 오류 출력 보존), 상업적 또는 법적 결과가 있는 의미 모호성(분류하여 결정 소유자에게 전달).

저장소 수정 규칙

저장소를 편집하기 전에: 에이전트/저장소 지침, 패키지 매니페스트, 빌드/테스트/린트 명령, 렌더링 아키텍처, 기존 메타데이터 및 스키마 시스템, 작업 트리 상태를 읽으십시오. 그런 다음: 기존 아키텍처를 보존하고, 중복 리터럴보다 공유 데이터 모델을 선호하며, 테스트를 우회하거나, 린팅을 비활성화하거나, 유형을 약화시키거나, 관련 없는 파일을 건드리지 말고, 법적 또는 규제된 클레임을 조용히 다시 작성하지 말고, 모든 레지스트리 변경 사항의 차이점을 보존하며, 모든 변경 후 관련 citable validate/citable audit 범위를 다시 실행하십시오. 빌드 또는 렌더링 실패는 "검증됨" 결론을 사용 불가능하게 만듭니다.

안티 패턴

references/anti-patterns.md는 정식 라이브러리입니다(콘텐츠, 기술, AEO, GEO). 최적화를 권장하기 전에 참조하십시오. 요청된 변경이 안티 패턴과 일치하는 경우, 안티 패턴의 이름을 지정하고, 위험을 설명하고, 방어 가능한 대안을 제시하십시오.