camera-hal-sw-newsletter

Imported from TTolsun/camera-hal-sw-newsletter (AGENTS.md). Install upstream with npx skills add TTolsun/camera-hal-sw-newsletter. Copyright stays with the author.

저장소 작업 지침

이 저장소는 Camera HAL SW 뉴스레터 정적 사이트와 Node.js 기반 newsroom 자동화 저장소입니다. 기본 응답은 한국어로 작성하세요. 단, 파일명, 명령어, 코드 식별자, JSON key, enum 값, URL, 외부 제품명과 공식 출처명은 원문을 유지하세요.

저장소 전체 원칙 (Repository-wide Principles)

• 발행 안전성이 최우선입니다. 검증을 약화하거나 quality threshold(품질 기준 점수)를 낮춰 통과시키지 마세요.
• 뉴스레터 발행은 PR 기반입니다. 생성 workflow가 main에 직접 발행하거나 자동 merge하지 않습니다.
• 출처 없는 main article, dated evidence(날짜 근거) 없는 watch/reference page, source gap(출처 누락)이 남은 article을 발행하지 않습니다.
• 외부 기사 이미지는 임의 URL로 대체하지 않습니다. 기존 image resolver와 assets/images/fallback/ 계약을 따릅니다.
• selectedImage는 최종 발행 가능한 이미지 경로로 취급합니다.
• 과거 생성 산출물인 articles/content/newsroom/**, articles/content/collected-news/**, 기존 articles/newsletters/** 파일은 명시 요청 없이 대량 수정하지 않습니다.

발행 주기와 정책 (Cadence & Policy)

• 발행 주기는 주간(weekly) 입니다. 주간호는 그 자체로 완결(self-contained)이어야 하며, 같은 내용을 과거 daily 페이지로 링크해 대신하지 않습니다.
• 정책 값의 source of truth는 src/shared/config/newsletter-policy.json입니다. README.md와 docs의 정책 텍스트는 이 JSON에서 생성된 것이므로 직접 고치지 마세요. JSON을 수정한 뒤에는 npm.cmd run sync:policy-docs를 실행합니다(check:policy-docs가 validate에서 검증).

Encoding / Shell 규칙

• Repository text file은 명시 예외가 없는 한 UTF-8 without BOM으로 저장합니다.
• 한글이나 non-ASCII 문자가 포함될 수 있는 repository text file을 PowerShell Set-Content, Out-File, > redirection으로 rewrite하지 않습니다.
• Text file 수정은 patch 기반 편집이나 UTF-8 보존이 명확한 Node.js 도구를 사용합니다.
• Commit 전에는 npm.cmd run check:encoding 또는 이를 포함한 npm.cmd run validate를 실행합니다.
• Repository-wide line ending normalization은 별도 작업으로만 다루며, 일반 feature/fix PR에서 git add --renormalize .를 실행하지 않습니다.

디렉터리 구조 (Structure)

• root index.html과 articles/css/, articles/assets/는 정적 사이트 surface입니다(#262 phase 6: 공개 출력물은 모두 articles/ 아래에 위치하고, Pages Actions 배포가 _site/ 루트로 조립해 서빙 URL을 보존합니다).
• src/shared/data/news-sources.json은 machine-readable source of truth이고 docs/NEWS_SOURCES.md는 사람이 검토하는 editorial view입니다.
• articles/content/collected-news/YYYY-MM-DD/는 raw candidate output입니다.
• articles/content/newsroom/YYYY-MM-DD/는 reporter, editor, fact-check, quality, retry, QA review artifact입니다.
• articles/newsletters/는 public issue output인 newsletter.md와 index.html입니다. 주간 전환 후 공개 이슈는 YYYY-Wnn/을 쓰고, 전환 이전 daily 이슈는 YYYY-MM-DD/ 형태로 남아 있습니다. 중간 산출물(위 두 줄)은 계속 YYYY-MM-DD/입니다.
• 실제 구현과 tooling은 모두 src/에 있습니다. src/shared/**(공통 런타임·도메인·tooling·런타임 config/data), src/collector/**, src/discovery/**, src/generator/**(select/reporter/editor/quality/repair/diagnostics/render/validate/publish)로 나뉩니다. #262 재구성으로 root scripts/*.js wrapper와 scripts/lib/는 제거되었고 scripts/에는 더 이상 실행 코드가 없습니다.
• .github/workflows/는 newsroom PR workflow와 validation workflow입니다.

Scoped AGENTS 정책 (Scoped AGENTS Policy)

Root AGENTS.md는 저장소 전체에 적용됩니다. 폴더별 scoped AGENTS.md는 그 폴더가 저장소 기본값과 다른 safety-critical 규칙이나 계약을 가질 때만 추가합니다.

scoped AGENTS.md는 이 root 지침을 상속합니다. 즉 폴더별 제약을 더할 뿐, 저장소 전체 규칙을 대체하지 않습니다. 이 root 파일과 충돌하는 scoped 지침을 만들지 마세요.

보기 좋은 대칭을 맞추려는 목적만으로 scoped AGENTS.md를 추가하지 마세요. 그 폴더에 위험이나 모호함을 실질적으로 줄이는 규칙이 있을 때만 추가합니다.

저장소 파악은 llm-wiki부터

저장소 구조, 정책 값, 모듈 위치가 궁금하면 코드 grep 전에 llm-wiki/index.md(로컬 전용, gitignored — 없는 환경에서는 건너뜁니다)를 먼저 확인하세요. 코드에서 파생된 문서이므로 정확한 수치와 경로는 코드로 재확인합니다. 스키마와 운영 규칙은 llm-wiki/AGENTS.md 참고.

명령어 (Commands)

Windows PowerShell에서는 npm보다 npm.cmd를 사용하세요.

npm.cmd run test        # test:unit (run-node-tests.js over src) + test:script
npm.cmd run validate    # full safety gate (encoding, hygiene, fixtures, policy, config, site, quality, localization, ...)
npm.cmd run ci          # test + validate
npm.cmd run collect     # collect candidates from src/shared/data/news-sources.json -> articles/content/collected-news/
npm.cmd run generate    # run the LLM newsroom pipeline (needs GEMINI_API_KEY for default provider)

validate는 여러 validate:*와 check:* 하위 스크립트를 길게 이어 붙인 체인입니다(package.json 참고). 변경 범위가 좁으면 해당 부분만 골라 실행하세요.

단일 테스트 파일을 직접 실행:

node src/shared/tooling/cli/run-node-tests.js src       # all unit tests (the runner)
node --test src/generator/test/contract/fixture-policy.test.js # one file via Node's built-in runner

구현 컨벤션 (Conventions)

• CommonJS require, 2칸 들여쓰기, 세미콜론, Node 20 compatibility.

검증 (Validation)

코드나 산출물을 수정한 뒤에는 기본적으로 아래 명령을 실행하세요.

npm.cmd run test
npm.cmd run validate

변경 범위가 좁더라도 관련 세부 검증이 있으면 함께 실행합니다. 예를 들어 source registry 변경은 npm.cmd run validate:config, 문서/표시값 변경은 npm.cmd run validate:localization을 포함합니다.

로컬 validate:quality가 실패하면 코드 버그로 단정하기 전에 미커밋 articles/content/newsroom/**/editor-draft.json이 남아 있는지 먼저 확인하세요. 이전 generate run이 남긴 잔재를 재채점해 생기는 거짓 양성이며(clean clone과 CI에는 재현되지 않음), 해당 파일을 치우고 다시 실행하면 해소됩니다. quality-report를 덮어써서 맞추는 방어 패치는 금지입니다. 자세한 이유는 articles/content/AGENTS.md 참고.

Local Agent Scratch (작업용 임시 파일)

• Repository root PLAN.md와 PLAN.local.md는 repository artifact가 아니라 local-only scratch로 취급합니다.
• 작업 계획이 필요하면 .tmp/codex/<task>.md 또는 .codex/PLAN.local.md처럼 .gitignore로 보호되는 local-only 경로를 사용합니다.
• PR에는 product code, tests, official docs만 포함하고 Codex scratch, worklog, temp plan 문서는 commit하지 않습니다.
• memory/notes/checkpoint 성격의 Markdown, 작업 메모, TODO 정리, 임시 보고서는 repository 문서로 남기지 않습니다.
• 일시적으로 만든 실험용 코드, 디버깅용 one-off script, 재현/분석용 helper는 repository에 저장하지 않습니다. 필요하면 저장소 밖이나 OS 임시 디렉터리에서 사용하고 작업 완료 전에 삭제합니다.
• 과거 issue 해결, 리팩터링 계획, 디버그 baseline 같은 작업 중간 산출물은 repository 문서로 남기지 않습니다. 보존해야 할 정책이나 계약은 현재 코드와 맞는 canonical docs에 직접 통합합니다.

Fixture Trust Policy (fixture 신뢰 정책)

• generated artifact를 good/golden fixture로 자동 신뢰하지 않습니다. src/shared/test/fixtures/**/good에는 사람이 검수한 curated non-generated PASS sample만 두고, generated artifact에서 회귀 가치가 있는 경우 최소 입력만 bad/regression fixture로 보존합니다.
• 상세 fixture 신뢰 계약(ledger schema, provenance enum, seed-evidence 경계, layout 계약, 전체 exclusion 목록)의 정본은 src/AGENTS.md입니다.

PR Scope (PR 범위)

변경은 좁게 유지하고 관련 파일만 stage하세요. commit 메시지는 간결한 명령형 영어 제목을 사용합니다. unrelated cleanup, large directory reorg, workflow behavior 변경은 사용자 요청 없이 묶지 않습니다.