From 04754b99ad47de526478e1fd6e0dc934ec0311df Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 16:56:19 +0900 Subject: [PATCH 1/2] docs(product-goal-directive): replace directive text with owner's 2026-09-02 revision MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The owner supplied a substantially revised nine-section standing directive (pasted directly into session, not via PR) that expands the PR-repair-not-close policy, adds a full i18n/DB-translation-ledger subsection, adds an ontology-ownership split and a "core foundation" canonical-owner taxonomy, softens the Rust-only mandate into an ADR-documented exception path, and adds explicit CI model-routing and timeout rules. Per this file's own stated policy ("edit this file in place... do not fork a second copy elsewhere"), replaced all nine quoted sections verbatim; kept and updated both reconciliation notes (§5 naming, §8 CI pool routing) against the new text rather than carrying forward stale guidance — the §5 wardnet example no longer appears in the new text, and the §8 orchestrator/free pin is now the owner-confirmed live state for both OpenCode Review and Strix per ADR-0003's 2026-08-30/2026-09-02 amendments. Full revision rationale in docs/doctoring/product-goal-directive.md. Co-Authored-By: Claude Sonnet 5 --- docs/doctoring/product-goal-directive.md | 102 +++++++++++++++++++++++ docs/product-goal-directive.md | 76 +++++++++-------- 2 files changed, 145 insertions(+), 33 deletions(-) diff --git a/docs/doctoring/product-goal-directive.md b/docs/doctoring/product-goal-directive.md index d752033602..cc41378e3b 100644 --- a/docs/doctoring/product-goal-directive.md +++ b/docs/doctoring/product-goal-directive.md @@ -86,3 +86,105 @@ fixed: conventions this record reconciles against. - ContextualWisdomLab/.github#1429 — the PR carrying this change and Devin Review's findings. + +## Revision (2026-09-02): directive text replaced in full + +- **Date:** 2026-09-02 +- **Subject:** The owner supplied a revised nine-section directive (pasted + directly into an interactive session, not as a PR) that is substantially + longer and more specific than the 2026-08-30 text it replaces. Per this + file's own stated policy ("edit this file in place... do not fork a second + copy elsewhere"), `docs/product-goal-directive.md`'s nine quoted sections + were replaced in full, verbatim, with the new text; only the two + reconciliation notes (§5 naming, §8 CI pool routing) and the surrounding + scaffolding (title, "why this file exists," `/goal` pointer) were kept and + updated, not the directive text itself. +- **PR:** ContextualWisdomLab/.github#1691 (product-goal-directive branch; + see the PR for the exact diff). + +### What changed in substance (not exhaustive — read the new §1-9 directly) + +- **§1** adds an explicit anti-pattern: a PR reaching zero open state must + come from a merge, or from a verified successor fully carrying forward its + valid delta — never from a bare Close. +- **§2** is substantially expanded: Close is redefined as a repair-not-close + action for most failure modes (single-writer/DDD violations, wrong + base/conflicts, ADR number collisions, premature Accepted status, + unprotected dependencies, missing test/fixture/contract) — demote to + Draft/Proposed and non-force restack/retarget instead of closing. Close + itself is now restricted to four cases: explicit user instruction, no valid + delta, a malicious change, or full successor carry-forward. Also newly + names https://github.com/epoko77-ai/im-not-ai for Korean phrasing/document + translation review (meaning/facts/figures/proper nouns must be preserved). +- **§3** adds an explicit decision-record bar: reconstructable by a first-time + reader (problem, constraints, alternatives, why chosen/rejected, evidence, + risk, effect, follow-up), evidenced against exact-head/logs/issues/PRs/ADRs. +- **§4** is new in large part: shadcn/ui is named as the product-owned + component source with Storybook as the verification environment; Keyverse + is scoped specifically to Direct Grant/ROPC or the Keycloak REST API as an + auth backend, with login/signup/recovery built as product-owned forms; and + a full i18n subsection is new — 8 supported languages, a DB-backed + versioned translation ledger (not files or a JS bundle), key-only + lookup/cache on server/native, and a dedicated repo for translation + workflow tooling if none exists yet. +- **§5** adds an ontology/semantic-layer ownership split (creation/publish vs. + catalog/consumption vs. interoperability contracts vs. EA decisions each + have a distinct owner; product domain truth/UL never moves) and loosens + identifier casing from "snake_case" to "snake_case, camelCase, or + PascalCase, snake_case preferred" for non-DB identifiers — see the + in-file reconciliation note for what still applies to DB objects + specifically. +- **§6** softens the earlier "all core math/perf code must be Rust, full + stop" framing: Python is now explicitly deprioritized rather than banned, + and a documented exception path exists (ADR-recorded scope/justification/ + removal condition) for the case where no practical Rust alternative exists + for a Python-only ML runtime dependency, with the hot path still kept in + Rust. +- **§7** adds a concrete performance target (p95 ≤ 20ms on every page, via + async processing + k6 E2E) and a frontend-performance subsection (bundle + size, heap, DOM, hydration, main thread, GC as replacement triggers for + dependencies/rendering approach/frontend stack). +- **§8** adds explicit, mechanical CI-routing rules that were previously only + implied: GitHub Actions model-backed workflows must pin to + `orchestrator/free` and must not name a provider/model/group or a paid + fallback — only a gateway token; missing capability fails closed rather + than routing around the free pool. Also adds an explicit default-null model + timeout policy (no app/agent/gateway-wide cap; upstream provider owns + timing out a stalled call) and admin-web requirements for per-model + enable/disable/restore with audit and API access. +- **§9** replaces the old flat repo list with a structured "core foundation" + ownership taxonomy (org/contracts; meaning/data; AI/ops; + identity/security/runtime; reusable capabilities), each entry naming its + canonical-owner repo and scope, plus an explicit anti-bypass rule: a + consumer must not copy/route around an immature or API-less owner repo — + the owner ships RED→GREEN→immutable-release first, the consumer adopts + after, and uses ports/ACLs/feature flags/test doubles as the boundary in + the meantime. + +### Reconciliation notes re-checked against the new text + +1. **§5 wardnet example.** The new text no longer names "wardnet" (or any + other product) as an "old name" example, so the specific conflict the + 2026-08-30 note flagged (wardnet is the *current* canonical name, not a + legacy one) no longer has a live trigger in the quoted text. Kept a + shortened note covering the still-relevant point: the DB-object grandfather + clause in `docs/CWL-MASTER-CONTEXT.md` §7. +2. **§8 CI pool routing.** The new text now states directly that GitHub + Actions model-backed workflows pin to `orchestrator/free` — which, as of + 2026-09-02, matches the owner-confirmed live state for **both** OpenCode + Review and Strix (see `docs/adr/0003-contextual-orchestrator-vendored-free-zdr.md`'s + 2026-08-30/2026-09-02 amendments). The 2026-08-30 note's original point + (this section describes orchestrator product capability, not CI routing + policy) is kept as historical context, with a status update on top stating + the risk it was tracking is now resolved and owner-reviewed. + +## Audit trail (revision) + +- `docs/product-goal-directive.md` — the revised directive and both + reconciliation notes. +- `docs/adr/0003-contextual-orchestrator-vendored-free-zdr.md` — the + 2026-08-30/2026-09-02 amendments confirming the `orchestrator/free` pin for + both OpenCode Review and Strix. +- `docs/CWL-MASTER-CONTEXT.md` §7 — the DB-naming grandfather clause the §5 + note still cites. +- ContextualWisdomLab/.github#1691 — the PR carrying this revision. diff --git a/docs/product-goal-directive.md b/docs/product-goal-directive.md index c76c4226e4..5c00d2cd29 100644 --- a/docs/product-goal-directive.md +++ b/docs/product-goal-directive.md @@ -1,6 +1,8 @@ # Product goal directive — autonomous PR/merge/development loop -**Status:** active standing directive · **Owner intent recorded:** 2026-08-30 · **Scope:** the full +**Status:** active standing directive · **Owner intent recorded:** 2026-08-30 · **Revised:** +2026-09-02 (nine-section text replaced in full with the owner's updated directive; see +`docs/doctoring/product-goal-directive.md` for what changed) · **Scope:** the full ContextualWisdomLab ecosystem (every repo an agent can reach from this org, leveraged in order of product responsibility / reuse boundary / docs / implementation / consumption — not by name). @@ -27,60 +29,68 @@ elsewhere; link to this file instead. ## 1. Execution goal and continuous loop -> 실행 목표와 지속 Loop 열린 PR마다 별도 중간 보고 없이 리뷰 확인→수정→GitHub Checks 재검증→병합→다음 개발을 반복하라. PRD를 읽고 Loop·Goal을 자율 생성·수정·제거해 PR을 병합 또는 0개로 만들며 상용화하라. 200억 달러에 판매할 자신이 있을 품질과 구매자가 체감할 제품 Gap 해소가 목표다. ADR·리서치·현행 데이터·PR로 기능 명세·PRD·TRD·UML·Gap·조치 상태를 도출해 docs/product-technical-gap-baseline.md에 갱신하라. 한 시간 간격으로 예약하고 메시지도 개선·갱신하라. PR·Issues 소진 후에도 제품 Gap 개발과 병합 Loop를 계속한다. 내가 온전히 소유한 ContextualWisdomLab 저장소를 레버리지 순으로 연계해 PR 병합·추가와 Connector 추가·수정 등 Ecosystem을 구축하라. Ecosystem 전 라이브러리 PRD를 숙지하고 조직·저장소명 대소문자를 지킨다. 리뷰·Checks 대기는 Blocker가 아니며, 실패 원인·수정·재실행 필요에 즉시 대응하며 안전한 작업을 계속한다. 결과 보고에 멈추지 말고 다음 Loop로 이동하라. 저장소는 이름이 아니라 제품 책임·재사용 경계·문서·구현·소비 저장소를 대조해 선택한다. ADR·Goal을 수시로 갱신하고 Goal 수정 불가 시 Loop를 갱신한다. +> 실행 목표와 지속 Loop 열린 PR마다 리뷰→수정→Checks 재검증→병합→다음 개발을 반복하라. PRD로 Loop·Goal을 조정하되 PR 0개는 병합이나 검증된 successor의 유효 delta 완전 승계로만 만들고 단순 Close하지 않는다. 목표는 200억 달러 판매 품질과 고객 체감 Gap 해소다. ADR·현행 근거·PR에서 PRD·TRD·UML·Gap·조치를 도출해 docs/product-technical-gap-baseline.md를 갱신하라. 매시간 예약 메시지를 개선한다. PR·Issues 소진 뒤에도 Gap 개발·병합과 ContextualWisdomLab 저장소·Connector 연계를 계속하며 PRD와 명칭 대소문자를 지킨다. 리뷰·Checks 대기는 Blocker가 아니다. 실패를 즉시 고쳐 재실행하며 안전한 일을 계속한다. 저장소는 책임·재사용·구현·소비 경계로 고르고 ADR·Goal·Loop를 갱신한다. -## 2. Concurrent operation, PR handling, and root-cause fixes +## 2. Concurrent operation, PR repair (not close), and root-cause fixes -> 동시 작업·PR 운영·근본 수정 원격 Agent의 동시 Commit·Push를 경합으로 단정해 Force Push·중단하지 말고 변경 취지·이유를 확인해 이어간다. Commit·Push 전 병합 여부를 확인하고 삭제 근거를 남긴다. Self-modifying/Source-fix Workflow는 목적 달성 후 삭제하고 잔존 시 관찰·제거한다. 가능한 PR은 Stack하고 not-merge-ready를 merge-ready로 전환한다. 유관 프로젝트 원인이 엮이면 함께 처리하고 Stacked PR을 중앙 OpenCode Agent가 리뷰하지 않으면 ContextualWisdomLab/.github를 수정한다. Agent 간 대화·Spawn을 활용한다. 수동 해법은 모두 코드·설정에 반영한다. PYTHONPATH=. 누락은 설정하고 GitHub Actions·런타임 오류는 로그·Root Cause Analysis로 제거한다. 전체 GitHub Checks 실패를 확인·수정한다. ContextualWisdomLab 내부 라이브러리 문제라면 원시 공급자 오류까지 고쳐 PR한다. 개발 프로세스에 https://github.com/DietrichGebert/ponytail 및 https://github.com/obra/superpowers 를 사용하되 superpowers의 "무조건 질문" 규칙은 무시한다. https://github.com/tirth8205/code-review-graph 와 https://github.com/colbymchenry/codegraph 도 사용하고 인덱싱은 스스로 수행한다. 이는 명시적으로 허가됐다. +> 동시 작업·PR 운영·근본 수정 동시 Commit·Push를 경합으로 단정하거나 Force Push하지 말고 취지를 잇는다. Commit 전 병합·삭제 근거를 남기고 목적을 마친 Self-modifying/Source-fix Workflow는 제거한다. PR을 Stack해 merge-ready로 만들고 유관 원인도 고친다. Stacked PR 리뷰가 빠지면 .github를 수리하고 Agent 대화·Spawn을 쓴다. single-writer·DDD 위반, 잘못된 base·충돌, ADR 번호 충돌, 성급한 Accepted, 미보호 dependency, 누락된 test·fixture·contract는 Close가 아닌 repair finding이다. Draft·Proposed로 낮추고 owner stack에 non-force restack·retarget해 수리한다. single-writer는 delta 폐기가 아닌 통합이다. 직접 못 고치면 successor가 delta를 완전 승계하고 predecessor를 잇는다. foundation 미착지 시 prerequisite를 완성하며 PR은 유지한다. 오폐쇄는 reopen·successor로 복구한다. Close는 사용자 명시, 유효 delta 없음, 악성 변경, 완전 승계에만 허용하며 표시는 종결이 아니다. 수동 해법은 코드·설정화하고 PYTHONPATH=.·Actions·runtime 오류는 로그 RCA로 없앤다. 내부 결함은 canonical owner·원시 공급자에서 고쳐 통합 CI와 release까지 잇는다. 경계나 공통 수요가 없을 때만 ADR로 제외한다. ponytail·superpowers를 쓰되 "무조건 질문"은 무시하고 code-review-graph·codegraph를 인덱싱한다. 한국어 문구·문서·번역에는 https://github.com/epoko77-ai/im-not-ai 를 적용하되 의미·사실·수치·고유명사를 보존한다. ## 3. Research, standards, and documentation traceability -> 연구·표준·문서 추적성 모든 개발은 최신 권위 국제 표준·논문을 조사해 APA 7th로 인용하고 doctoring에 기록하며 누락 근거를 보충한다. Local Zotero API가 되면 기존 자료를 읽거나 OA 논문을 추가한다. 논문·표준은 exact-head·전체 PR·내부 모듈·API에 모순 없이 결합하고 충돌을 수정한다. AGENTS.md, CLAUDE.md, ARCHITECTURE.md, CHANGELOG.md 등 ADR 문서를 상시 갱신하고 Core ERD, UML, PRD, TRD, user stories, storyboard, wireframes, Storybook inventory, security·test·operability baseline 및 필요한 그림을 포함한다. 릴리즈 가능하면 버전을 올려 배포하고 CHANGELOG.md를 갱신한다. GitHub.io를 언급하려면 페이지를 실제 출판한다. +> 연구·표준·문서 추적성 권위 표준·논문을 조사해 APA 7th로 인용하고 doctoring에 남긴다. Local Zotero API가 되면 자료·OA 논문을 보강한다. 근거는 exact-head·PR·모듈·API에 연결하고 모순을 고친다. AGENTS.md·CLAUDE.md·ARCHITECTURE.md·CHANGELOG.md·ADR와 ERD·UML·PRD·TRD·UX·security/test/operability를 갱신한다. 가능하면 버전·CHANGELOG를 올려 배포하고 GitHub.io를 언급하면 실제 출판한다. 의사결정은 처음 보는 사람도 문제·제약·대안·선택/기각 이유·근거·위험·효과·후속 조치를 재구성하게 구체적이고 자세히 기록한다. 결론·전제를 생략하지 말고 사용자·운영·장애 장면이 보이는 사례와 증거를 exact-head·로그·이슈·PR·ADR·실험에 연결해 다른 Agent가 검증·계속하게 한다. -## 4. UX/UI and customer-facing expression +## 4. UX/UI, i18n, and customer-facing expression -> UX·UI와 고객 표현 필요하면 Figma와 Storybook(https://github.com/storybookjs/storybook), https://github.com/nextlevelbuilder/ui-ux-pro-max-skill, https://github.com/local-over/Anti-Slop-UI 를 함께 쓴다. 반복 웹 객체는 디자인 토큰화·모듈화하고 Figma File ID를 ADR에 기록한다. Storybook 장면별·Edge case별 Event를 조사·구현한다. UX·UI는 반드시 스크린샷으로 검수하고 ui-ux-pro-max로 Accessibility, Touch & Interaction, Performance, Style Selection, Layout & Responsive, Typography & Color, Animation, Forms & Feedback, Navigation Patterns, Charts & Data를 정의·검토·반영·적용·감사한다. 내부 구현 경계를 고객 화면에 노출하지 않고 문구로 고객의 다음 행동을 돕는다. Frontend는 디자인 토큰 CSS, 버튼 Action Edge, Interaction UX, i18n 번역 일관성까지 테스트한다. +> UX·UI·i18n과 고객 표현 Figma·Storybook·ui-ux-pro-max·Anti-Slop-UI를 쓴다. 모든 UI는 재사용 객체이며 페이지는 그 조합이다. token·Figma ID를 ADR에 남긴다. Storybook에서 정상·로딩·빈·오류·권한·반응형·상호작용 상태를 문서화하고 스크린샷·E2E로 ui-ux-pro-max 전 범주를 감사한다. shadcn/ui는 제품 소유 component source, Storybook은 검증 환경이다. Frontend stack은 보안·유지보수·표준·접근성·측정 성능으로 고른다. 내부 경계를 숨기고 다음 행동을 안내한다. Keyverse는 인증 backend로 유지하되(Direct Grant/ROPC 또는 Keycloak REST API), 로그인·가입·복구는 제품 자체 form으로 만든다. token CSS·Action Edge·Interaction UX를 검증한다. i18n은 한국어·영어·일본어·중국어·베트남어·스페인어·독일어·프랑스어를 지원한다. UI 크기·줄바꿈·CJK·텍스트 팽창·font fallback·locale을 고려하고 언어별 Storybook·E2E로 잘림·겹침을 막는다. 번역 원장은 파일·JS bundle이 아닌 DB versioned resource다. server/native는 화면 key만 조회·cache하며 전체 catalog·무거운 i18n JavaScript·SPA를 전제하지 않는다. 공통 관리 제품이 없으면 새 저장소에서 제품별 번역·검토·승인·배포·rollback API·관리 UI를 제공한다. -## 5. Architecture, naming, and database conventions +## 5. Architecture, ontology, naming, and database conventions -> 아키텍처·명명·데이터베이스 소프트웨어는 중앙 .github, naruon, 다른 저장소와 연결 가능하게 만든다. DDD를 적용해 핵심·지원·일반 Subdomain, Bounded Context, Context Map, Ubiquitous Language를 ADR에 정의하고 Aggregate·Entity·Value Object·Domain Service·Repository·Domain Event·Invariant를 코드·API·DB·테스트에 일치시킨다. Aggregate는 최소 트랜잭션 경계로 두며 외부·레거시는 Anti-Corruption Layer로 격리하고 Shared Kernel은 최소화한다. 단독·반입 모듈 모두 우수한 모듈러 MSA를 지향하고 단일 소프트웨어가 Monolithic Architecture처럼 비대해지면 책임 경계에 따라 저장소를 분리한다. 소프트웨어명과 내부 호출자·클래스명이 다르거나 옛 이름(예: wardnet)을 쓰면 정식 이름으로 바꾼다. DB 객체명은 두 단어 이상의 snake case, Carmel case 또는 pascal case여야 하고 snake case를 우선한다. 위반명은 전부 치환한다. DB는 제3정규화와 Hot Partition 대비를 준수한다. Lock을 관리하고 불가하면 Read/Write DB를 분리한다. 영속화 경로의 항목별 UPSERT를 추적하고 없으면 계약을 보강한다. 명시적 구매자가 없는 제품은 코드 안팎의 Buyer를 정상 객체명으로 바꾼다. CSAP·SOC 2 인증을 고려한다. PII Masking이 업무를 마비시키므로 규정 준수형 비Masking 보호 대안을 설계한다. 실데이터 테스트·개발의 인명·기관명은 코드·ADR에서 익명화한다. GitHub Secrets의 PYPI API Key와 대부분 Public 배포라는 전제를 반영한다. +> 아키텍처·온톨로지·명명·데이터베이스 DDD의 Subdomain·Bounded Context·Context Map·Ubiquitous Language(UL)와 Aggregate·Entity·Value Object·Domain Service·Repository·Event·Invariant를 ADR·코드·API·DB·test에 맞춘다. Aggregate는 최소 transaction 경계, 외부·legacy는 ACL로 격리하고 Shared Kernel은 최소화한다. 비대한 Monolith는 책임별 저장소로 나누고 옛 이름을 고친다. 통합 온톨로지의 생성·publish, catalog·소비, 상호운용 계약, EA 결정은 owner를 분리한다. 제품의 domain truth·UL은 옮기지 않는다. release는 evidence·provenance·유효기간·confidence·status·locale label을 가진다. consumer는 released contract·ACL만 사용하며 파일 복사·cross-service SQL·미승인 publication을 금지한다. UI 번역과 ontology label 원장은 분리한다. 변수·상수·인자·필드·함수·메서드·클래스·타입·모듈·패키지·API·DB 객체·파일·디렉터리는 두 단어 이상 snake_case·camelCase·PascalCase로 명명하고 snake_case를 우선한다. 언어·framework·외부 계약 관례는 경계에서 변환하며 위반명은 치환한다. DB는 3NF·Hot Partition 대비·Lock·필요시 Read/Write 분리·항목별 UPSERT를 지킨다. placeholder Buyer는 실제 도메인명으로 바꾼다. CSAP·SOC 2를 고려한다. PII Masking이 업무를 마비시키면 준수형 비Masking 대안을 설계한다. 실데이터 인명·기관명은 익명화하고 PYPI API Key·Public 배포 전제를 반영한다. -**Reconciliation (flagged by Devin Review on this PR, 2026-08-30 — see `docs/doctoring/product-goal-directive.md`):** taken verbatim and cross-referenced against the rest of the ecosystem's own naming history, this section's quoted text reads backwards in two places: - -- It names "wardnet" as an example of an "old name" (옛 이름) to rename *away from*. But per `docs/CWL-MASTER-CONTEXT.md` §3/§10, `waf-ids-ai-soc` → **wardnet** is an already-completed rename — wardnet is the current canonical product name, not a legacy one. Read this section's "old name" example as applying to whatever pre-rename name a component still uses internally (stray `waf-ids-ai-soc` references, say), never as license to rename wardnet itself away from its current name. -- "위반명은 전부 치환한다" ("replace all violating [DB object] names") would, read literally, force-rename existing CamelCase/PascalCase database objects. That contradicts the binding convention in `docs/CWL-MASTER-CONTEXT.md` §7: *"DB object names = 2+ word snake_case (don't rename existing Camel/Pascal)."* The §7 rule governs: 2+-word snake_case is required for **new** DB objects; existing CamelCase/PascalCase objects are grandfathered and must not be force-renamed. - -Per this file's own conflict policy above: this note is the resolution, and `docs/CWL-MASTER-CONTEXT.md` §7 is the document that was right — do not force-rename wardnet or existing Camel/Pascal DB objects on the strength of this section's verbatim wording alone. +**Reconciliation (carried forward from the 2026-08-30 review; re-checked against this 2026-09-02 +revision):** this section's earlier wording named "wardnet" as an example of an "old name" to rename +away from, which contradicted `docs/CWL-MASTER-CONTEXT.md` §3/§10 (`waf-ids-ai-soc` → **wardnet** is +an already-completed rename). The 2026-09-02 text above no longer names wardnet or any other product +by name in that sentence, so that specific conflict is resolved. The remaining point still worth +flagging: "위반명은 치환한다" now explicitly permits snake_case, camelCase, *or* PascalCase (snake_case +preferred) for identifiers generally, which is looser than the old "snake_case only" reading — but for +**database objects specifically**, `docs/CWL-MASTER-CONTEXT.md` §7's grandfather clause still governs: +2+-word snake_case is required for **new** DB objects; existing CamelCase/PascalCase DB objects are +grandfathered and must not be force-renamed on the strength of this section's general wording alone. ## 6. Implementation language, computation, and measurement principles -> 구현 언어·연산·측정 원칙 Docstring Coverage, Test Coverage, Edge Case Test Coverage를 각각 100%로 만든다. 초보자가 별도 코드 분석 없이 이해할 수 있을 만큼 충분한 docstring을 제공한다. 수리과학, Psychometrics, Exploratory Data Analysis, 데이터과학의 모든 core 연산 레이어는 Python으로 구현하지 말고 무조건 Rust로 작성한다. Vector 연산, Linear Algebra, Matrix Algebra, LLM token size 연산도 포함한다. GPU와 CPU multithreaded 실행을 지원하고 context switching을 최소화한다. 속도·안정성·보안이 중요한 일반 소프트웨어도 Rust를 사용하며, 기존 타 언어 구현은 전환·리팩터링하거나 명확한 Rust API Call 경계로 분리한다. 확률표집 계약에는 표본 설계, 오차 목표, 실패 분모를 명시해 ADR과 감사 코드에 반영한다. Atomistic fallacy를 막도록 다층구조·다중소속 모델링을 고려·구현하고 시간 흐름을 반영하는 모델도 포함한다. 가중치는 임의로 정하지 말고 수리과학·Psychometrics에서 추정된 값, 특히 fast-mlsirm이나 TEPP처럼 논문 근거가 있는 모형을 사용한다. 어떠한 휴리스틱과 Rule of thumbs도 금지하며, 근거 미확정 상태로 방치하지 말고 ContextualWisdomLab의 추론 엔진을 최대한 활용하고 SOLID 원칙을 지킨다. Deprecation Warning은 Suppression하지 말고 근본 문제를 해결한다. 합성 데모 데이터는 Unit test에는 쓸 수 있으나 Production에 반영하지 않는다. Python 웹 서버는 Multithreading을 지원하고 GIL이 문제면 Python 3.14를 사용한다. +> 구현 언어·연산·측정 원칙 Docstring·Test·Edge Case Coverage는 각 100%다. 수리과학·Psychometrics·EDA·데이터과학 core와 성능·보안 runtime은 Rust로 만들며 Vector·Linear/Matrix Algebra·token size·GPU·CPU multithreading을 포함한다. Python은 비선호며 LLM 편의로 고르지 않는다. Python 전용 ML runtime에 실용적 Rust 대안이 없을 때만 그 부분에 쓰며 범위·근거·제거 조건을 ADR에 남기고 hot path는 Rust로 둔다. 확률표집은 설계·오차 목표·실패 분모를 명시하고 다층·다중소속·시간 모델로 Atomistic fallacy를 막는다. 가중치는 fast-mlsirm·TEPP 등 논문 근거로 추정하며 휴리스틱을 금지한다. 미확정 근거는 추론 엔진·SOLID로 해결한다. Deprecation Warning은 근본 해결하고 합성 data는 Unit test에만 쓴다. Python web server는 multithread이며 GIL 병목은 3.14나 Rust로 푼다. ## 7. Realistic verification, load, and container testing -> 현실성 있는 검증과 부하·컨테이너 테스트는 제품 특성에 맞는 현실 사례와 정확성 기준을 포함한다. Psychometrics는 true parameter 대비 estimation RMSE와 true parameter 추정 재현성을 검증하고, 음악 분석은 실제 음원이 기대 분석값을 내는지 확인한다. 웹을 지원하면 Asynchronous 처리를 구현해 무응답을 방지하고 k6 end-to-end load test로 동시 접속 능력과 병목을 측정·개선한다. close_connection을 인스턴스 속성으로만 가정하는 잠재 버그를 점검한다. Docker는 Podman 또는 colima로 대체할 수 있다. 컨테이너 병목이면 shm_size와 PostgreSQL 등 응용 설정을 하드웨어에 맞게 자동 튜닝한다. 주로 compose로 운영해 k8s 전환성을 확보한다. Docker container 프로젝트명은 고정하되 테스트 격리 때만 override하고 달성 후 격리 컨테이너를 제거한다. MLX·CPU·CUDA·OpenCL의 Docker/Podman/Colima 처리법을 ADR에 기록·반영하고 Native Module 분리가 필요하면 독립 서비스로 개발한다. +> 현실성 있는 검증과 부하·컨테이너 테스트는 현실 사례와 제품별 정확성 기준을 쓴다. Psychometrics는 true parameter 대비 RMSE·재현성을, 음악은 실제 음원의 기대값을 검증한다. 웹은 비동기 처리·k6 E2E를 적용해 모든 페이지 p95≤20ms를 맞춘다. 초과하면 profile하고 runtime·언어·framework가 원인이면 계약·정확성을 보존해 Rust 우선 기술·hot path·언어로 바꾼다. 표본 축소·측정 제외·비현실적 cache warm-up은 금지한다. JavaScript bundle·heap·DOM·hydration·main thread·GC가 메모리·지연을 키우면 dependency·rendering·Frontend stack을 교체한다. close_connection도 점검한다. Docker는 Podman·colima로 대체 가능하다. 병목이면 shm_size·PostgreSQL을 장비에 맞춰 튜닝한다. compose로 k8s 전환성을 지키고 프로젝트명은 test 격리 때만 바꾼다. MLX·CPU·CUDA·OpenCL 처리법을 ADR에 남기고 Native Module은 필요시 독립 service로 분리한다. ## 8. LLM, orchestration, and embedding -> LLM·오케스트레이션·Embedding LLM이 필요한 테스트는 contextual-orchestrator 기반 OpenCode Agent로 만든다. contextual-orchestrator는 GitHub Secrets의 BYTEZ_API_KEY, NVIDIA_NIM_API_KEY, NVIDIA_NIM_API_KEY_SUB, OPENROUTER_API_KEY, OPENAI_API_KEY를 모두 써 auto model discovery로 최적 모형을 제공한다. embedding·responses·completions, audio, video, image, ommi-modal 등 가용 모델을 폭넓게 지원한다. 가능하면 반입해 쓰고 발견한 해당 저장소 문제도 함께 수정한다. LLM 사용 소프트웨어와 contextual-orchestrator는 Fugu·Conductor·TRINITY 연구를 근거로 단일 모델 라우팅과 심층 다중 Agent 오케스트레이션 사이의 계산량을 배분한다. 워크플로 단계, 재귀 깊이, 작업 분해, 접근 목록으로 test-time compute를 조절하고 역할별 reasoning effort를 다르게 하며 추론 수준 ablation을 수행한다. 속도는 핵심 고려사항이 아니며 정확성을 우선한다. 중앙 OpenCode, Strix, Noema는 모델당 두 시간 이상 걸릴 수 있음을 수용한다. LLM Chat model은 chat completion API와 responses API를 모두 지원하고 json_object와 json_schema를 모두 처리한다. Embedding은 문단·구문·DOM·송수신자 등 의미 단위를 식별해 chunking한다. 본문에 base64 이미지가 있으면 텍스트 인식, 객체 인식, 태그 설명, 이미지 별도 검색 방법을 연구 근거와 함께 DB 설계에 넣고 원래 삽입 위치를 보존해 그림 맥락까지 검색·표현한다. GitHub Actions scheduler는 contextual-orchestrator 기반 OpenCode Agent로 전환한다. COPILOT_GITHUB_TOKEN은 쓰지 않고 기존 리뷰 Agent 키 체계를 유지한다. - -**Note (flagged by CodeRabbit on this PR, 2026-08-30):** section 8's quoted text describes `contextual-orchestrator`'s general product capability — broad model/modality support and all-five-secret auto model discovery as a *design principle for the orchestrator itself*. It does not specify, and must not be read as overriding, which pool each CI consumer routes through: that is governed exclusively by `docs/adr/0003-contextual-orchestrator-vendored-free-zdr.md` and its doctoring records — `OpenCode` and `Noema` use the fail-closed, ZDR-prioritized `orchestrator/free` pool; only `Strix` security analysis uses the provider-diverse `orchestrator/auto` pool; private/internal review targets require an attested ZDR-only catalog and never fall back to a non-ZDR provider. Do not loosen any CI consumer's pool or credential scope on the strength of this section's general wording alone. +> LLM·오케스트레이션·Embedding LLM 작업은 contextual-orchestrator(CO) Agent로 만든다. BYTEZ_API_KEY·NVIDIA_NIM_API_KEY·NVIDIA_NIM_API_KEY_SUB·OPENROUTER_API_KEY·OPENAI_API_KEY로 auto discovery해 embedding·responses·completions·audio·video·image·omni-modal을 지원하고 released API·client·schema로 연결한다. 통합 CI는 .github reusable workflow와 thin caller로 구성한다. owner PR·release·consumer 변경마다 exact SHA로 build·API/schema contract·E2E·model behavior·security·SBOM·provenance를 검증한다. 결함은 owner에서 RED→fix→GREEN→release하고 consumer version을 올린다. mutable head·branch URL·cross-repo source·workflow 복제를 금지하며 bridge에는 owner issue·만료·삭제 조건을 둔다. GitHub Actions의 model-backed workflow는 `orchestrator/free`로 고정한다. 무료 후보 discovery·routing·fallback은 CO 내부에서만 한다. workflow는 provider·model·group명·유료 fallback을 지정하지 않고 gateway token만 쓴다. capability가 없으면 유료 우회 없이 fail closed해 free pool·contract·CI를 보완한다. Provider group명은 하드코딩하지 않는다. group은 별칭이며 modality·context·reasoning·tool·structured output·streaming·가격·지연·가용성·정확도 등 검증된 특성으로 선택·fallback한다. Model timeout은 application·Agent·Gateway 공통 상한 없이 기본 null이다. 통신 장애는 upstream provider가 끝낸다. 관리자 Web은 모델별 조회·설정·해제·복원, 단위·우선순위·상속·검증·감사·API를 제공하고 설정된 모델만 제한한다. reasoning·streaming·tool call은 시간만으로 끊지 않으며 사용자 취소·provider 종료·관리자 timeout을 구분한다. Fugu·Conductor·TRINITY 근거로 단일·다중 Agent의 test-time compute를 단계·재귀·분해·접근·역할별 effort로 배분·ablation한다. 정확성을 우선하고 OpenCode·Strix·Noema의 모델당 2시간 이상을 수용한다. Chat은 completions·responses와 json_object·json_schema를 지원한다. Embedding은 의미 단위로 나누고 base64 이미지의 인식·검색·삽입 위치·맥락을 보존한다. -**Note (2026-08-30, superseded by the merged pin flip — see the correction below):** an earlier draft of this note said Strix stayed on `orchestrator/auto` pending `free_family_diversity` reaching `>= 2`. That is no longer true and must not be read as current: `.github/workflows/strix.yml` now hardcodes `STRIX_MODEL`/`CONTEXTUAL_ORCHESTRATOR_POOL` to `orchestrator/free` and fails closed on any other value. This note originally went on to say that ADR-0003's 2026-08-30 amendment "records the owner's decision to accept the residual single-outage-domain risk immediately rather than wait for the evidence-gated threshold this note originally described" — that framing was false, as ADR-0003's own 2026-08-31 correction now records: no owner reviewed or accepted this switch or its risk. `free_account_diversity` (`scripts/ci/contextual_orchestrator_review_policy.py`; renamed from `free_family_diversity` once every KV credential became an independent discovery account rather than being grouped into a vendor "family", see #1468) remains useful as ongoing monitoring evidence for that open, unreviewed risk, not as a gate blocking the pin. +**Status update (2026-09-02, supersedes the 2026-08-30 note below):** the section above now states +directly that every GitHub Actions model-backed workflow pins to `orchestrator/free` — and this is now +the actual, owner-reviewed state, not just this section's aspiration. Per +`docs/adr/0003-contextual-orchestrator-vendored-free-zdr.md`'s 2026-08-30/2026-09-02 amendments, the +owner explicitly confirmed on 2026-09-02 (in the `/loop` input for the contextual-orchestrator +integration work: *"Contextual-Orchestrator의 모델은 GitHub Actions Workflow 이용에 관해 +`orchestrator/free`로 고정"*) that **both** OpenCode Review and Strix are pinned to `orchestrator/free` +— resolving the ADR-0003-flagged "Strix switched without owner review" risk the 2026-08-30 note below +was tracking. Treat the free-pin for both consumers as settled; do not re-flag it as an unreviewed risk. -## 9. Reference libraries, tool invocations, and ecosystem repositories +**Note (2026-08-30, historical — the risk it flagged is now resolved per the update above):** section +8's quoted text describes `contextual-orchestrator`'s general product capability — broad +model/modality support and all-five-secret auto model discovery as a design principle for the +orchestrator itself. It did not specify, and should not have been read as overriding, which pool each +CI consumer routed through on its own — that distinction lived in +`docs/adr/0003-contextual-orchestrator-vendored-free-zdr.md`. Private/internal review targets still +require an attested ZDR-only catalog and never fall back to a non-ZDR provider; that part is unchanged. -> 참고 라이브러리와 호출 @Superpowers @GitHub @Figma @Visualize @Context7 @Product Design @Consensus를 활용한다. +## 9. What "core foundation" means, and its development/use boundary -- **TEPP** — https://github.com/ContextualWisdomLab/TEPP — 다국어·시간·관계 측정용 Temporal Event Psychometrics Platform이며 통계·심리측정 산술은 Rust로 구현한다. -- **contextual-orchestrator** — https://github.com/ContextualWisdomLab/contextual-orchestrator — 논문 근거의 contextual model orchestration lab·enterprise admin design. -- **fast-mlsirm** — https://github.com/ContextualWisdomLab/fast-mlsirm — simple-structure MLSIRM/MLS2PLM은 Jeon, Jin, Schweinberger, and Baugh(2021), Kang and Jeon(2025), Molenaar and Jeon(2026)을 따른다. 인접 화면: Angoff delta-plot DIF(docs/delta_plot_dif.md), Bradley–Terry MM ranking(docs/bradley_terry_mm.md). 주요 인용·결정: docs/traceability/research-basis.md, docs/adr/README.md. 점수 해석·공정성은 AERA·APA·NCME(2014)를 따르며 이는 CWE/OWASP/NIST 통제가 아니다. -- **keyverse** — https://github.com/ContextualWisdomLab/keyverse — Keycloak 기반 독립 컴포넌트(Apache-2.0)이자 ContextualWisdom ecosystem 중앙 Identity Provider. -- **RankWeave** — https://github.com/ContextualWisdomLab/RankWeave — Python 3.10+용 무의존성·저장소 비종속 retrieval fusion/evaluation/statistical comparison/tuning/TREC benchmarking/auditable CLI workflow. -- **ThreadWeave** — https://github.com/ContextualWisdomLab/ThreadWeave — runtime dependency 없는 Python용 표준 기반 JWZ/RFC 5256 이메일 reference threading. -- **disksage** — https://github.com/ContextualWisdomLab/disksage — Windows/Linux/macOS 디스크 공간 관리자. 드라이브를 스캔하고 완전 오프라인 온디바이스 LLM이 삭제 안전성을 조언하며 OWL ontology로 파일을 정리한다. -- **wardnet** — https://github.com/ContextualWisdomLab/wardnet — ContextualWisdomLab Rust-first gateway·SOC control-plane baseline. -- **LineageWeave** — https://github.com/ContextualWisdomLab/LineageWeave — 명시적 선후행 링크 없는 짧은 timestamped record에서 git-branch식 lineage DAG를 재구성해 평면 자료를 탐색 가능한 branching thread로 바꾼다. 수리 연산은 소관이 아니므로 다른 라이브러리로 이관한다. +> Core foundation의 의미와 개발·사용 경계 @Superpowers·@GitHub·@Figma·@Visualize·@Context7·@Product Design·@Consensus를 쓴다. Core foundation은 전 제품의 공통 설치물이 아니다. 여러 제품에서 반복되는 책임을 한 저장소가 canonical owner로서 독립 배포·versioned contract를 제공하는 선택형 control plane·service·library다. 보호 브랜치의 문서·API/schema·release evidence로 역할·성숙도를 확인하며 open PR은 Proposed 상태다. 조직·계약 — .github: 공통 CI·review·security·release; enterprise-architecture-core: 전사 Context Map·architecture decision; context-graph-contracts: assertion·event·schema·fixture·conformance. domain truth는 제품에 남긴다. 의미·데이터 — ConceptWeave: ontology·semantic-layer 생성·검증·release. semantic-data-portal: catalog·governance·검색·제공. EmbedRelay: embedding identity·migration. mhtml-etl-gateway: MHTML 검사·schema proposal·load lineage. AI·운영 — CO: provider discovery·model capability·routing/delegation/verification/admin. noema: GitHub Actions OIDC 단기 repository capability·exact-revision evidence. pg-llm-batch: DB token count·batch 처리. Identity·보안·runtime — keyverse: identity·federation·token. EgressWeave: 안전한 outbound HTTP. OriginWeave: governed browser. pingora-gateway: Rust edge. quarantine-sandbox-runtime: 격리. appguardrail: scan·SARIF·remediation. wardnet: gateway·WAF·IDS·SOC. 재사용 기능 — fast-mlsirm: IRT·MLSIRM. TEPP: 다국어·시간·event·relation 측정. RankWeave: retrieval fusion·evaluation·통계 비교·tuning·TREC. ThreadWeave: JWZ/RFC 5256 threading. inkspan: editor·serialization·문서 변환. DiagramWeave: diagram patch·render·CLI·LSP. owner가 미성숙하거나 API가 없어도 consumer가 복제·우회하지 않는다. owner에서 RED test→기능·문서·release를 개발해 CI GREEN과 immutable version을 낸 뒤 채택한다. 그 전에는 port·ACL·feature flag·test double로 경계를 지키고 owner의 source·DB·임시 branch를 직접 읽지 않는다. ## How to point a `/goal` session at this directive @@ -88,7 +98,7 @@ Because `/goal` truncates at 4000 characters, do not paste the sections above in short pointer, e.g. (Korean, ~260 chars, well under the cap): ```text -/goal ContextualWisdomLab/.github의 docs/product-goal-directive.md 전문을 지침으로 삼아 실행하라. 열린 PR마다 리뷰 확인→수정→Checks 재검증→병합→다음 개발을 중간 보고 없이 반복하고, PR·Issue 소진 후에도 Gap 기반 개발을 계속한다. 이 문서의 9개 절 전체(실행 루프, 동시작업/근본수정, 연구추적성, UX/UI, 아키텍처/DB, 언어/측정, 검증/부하, LLM/오케스트레이션, 참고 라이브러리)를 매 사이클 적용 대상으로 취급하고, 이 문서와 docs/CWL-MASTER-CONTEXT.md §7이 상충하면 상충을 해소하고 두 문서를 함께 갱신하라. 한 시간 간격으로 재예약하라. +/goal ContextualWisdomLab/.github의 docs/product-goal-directive.md 전문을 지침으로 삼아 실행하라. 열린 PR마다 리뷰 확인→수정→Checks 재검증→병합→다음 개발을 중간 보고 없이 반복하고, PR·Issue 소진 후에도 Gap 기반 개발을 계속한다. 이 문서의 9개 절 전체(실행 루프, 동시작업/PR 수리/근본수정, 연구추적성, UX/UI/i18n, 아키텍처/온톨로지/DB, 언어/측정, 검증/부하, LLM/오케스트레이션, core foundation 경계)를 매 사이클 적용 대상으로 취급하고, 이 문서와 docs/CWL-MASTER-CONTEXT.md §7이 상충하면 상충을 해소하고 두 문서를 함께 갱신하라. PR은 유효 delta의 successor 완전 승계 없이 단순 Close하지 말라. 한 시간 간격으로 재예약하라. ``` When this directive itself changes (the user revises a section, or an agent finds it conflicts with From 23f90bca2ec2513966272723f8a0042ffc9da952 Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Wed, 2 Sep 2026 16:56:46 +0900 Subject: [PATCH 2/2] docs(product-goal-directive): fix PR number placeholder in doctoring record Co-Authored-By: Claude Sonnet 5 --- docs/doctoring/product-goal-directive.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/doctoring/product-goal-directive.md b/docs/doctoring/product-goal-directive.md index cc41378e3b..82fc06ef7c 100644 --- a/docs/doctoring/product-goal-directive.md +++ b/docs/doctoring/product-goal-directive.md @@ -99,7 +99,7 @@ fixed: reconciliation notes (§5 naming, §8 CI pool routing) and the surrounding scaffolding (title, "why this file exists," `/goal` pointer) were kept and updated, not the directive text itself. -- **PR:** ContextualWisdomLab/.github#1691 (product-goal-directive branch; +- **PR:** ContextualWisdomLab/.github#1698 (product-goal-directive branch; see the PR for the exact diff). ### What changed in substance (not exhaustive — read the new §1-9 directly) @@ -187,4 +187,4 @@ fixed: both OpenCode Review and Strix. - `docs/CWL-MASTER-CONTEXT.md` §7 — the DB-naming grandfather clause the §5 note still cites. -- ContextualWisdomLab/.github#1691 — the PR carrying this revision. +- ContextualWisdomLab/.github#1698 — the PR carrying this revision.