docs: establish canonical product and trust-boundary documentation - #71
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughNoema의 런타임 구조와 신뢰 경계를 문서화했습니다. Worker는 workflow ref와 immutable SHA pair를 검증합니다. readiness, API 계약, 운영 문서와 회귀 테스트를 갱신했습니다. Changes아키텍처 및 workflow 신뢰
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant GitHubActions
participant CloudflareWorker
participant NoemaOidcReplayGuard
participant GitHubApp
GitHubActions->>CloudflareWorker: /exchange 요청
CloudflareWorker->>CloudflareWorker: workflow ref·SHA claims 검증
CloudflareWorker->>NoemaOidcReplayGuard: jti replay 검증
CloudflareWorker->>GitHubApp: installation token 교환
GitHubApp-->>CloudflareWorker: 저장소 범위 단기 토큰
CloudflareWorker-->>GitHubActions: exchange 응답
Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/doctoring/architecture-trust-boundaries.md (1)
70-78: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick winDurable Object alarm의 제한된 자동 재시도 semantics를 기록하세요.
현재 문서는 alarm이 at-least-once로 실행되고 실패 시 자동 재시도된다고 설명합니다. Cloudflare 공식 문서는 자동 재시도가 exponential backoff와 최대 6회로 제한되며, 무기한 복구가 필요하면 handler가 새 alarm을 명시적으로 예약해야 한다고 설명합니다. 이 제한과 reschedule 요구사항을 추가하세요. (developers.cloudflare.com)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/doctoring/architecture-trust-boundaries.md` around lines 70 - 78, Update the Durable Object alarm semantics section to state that automatic retries use exponential backoff and are limited to a maximum of six attempts. Also document that handlers requiring recovery beyond those retries must explicitly schedule a new alarm, while preserving the existing at-least-once and stale-state validation guidance.test/architecture-documentation.test.ts (1)
5-35: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win문서 회귀 검사를 실제 runtime contract 검사로 강화하세요.
현재 테스트는 required 문자열과 두 개의 오래된 문구만 검사합니다.
wrangler.toml의main,src/entrypoint.ts·src/worker.ts·src/index.ts의 layer ownership, Durable Object binding/class, route method를 비교하지 않습니다. 따라서 runtime 구조가 바뀌어도 일부 키워드가 남아 있으면 테스트가 통과합니다. 문서와 실제 설정·소스의 핵심 관계를 직접 assertion으로 추가하세요.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@test/architecture-documentation.test.ts` around lines 5 - 35, Strengthen the architecture documentation tests beyond keyword checks by asserting the runtime contract against actual configuration and source ownership. In the existing tests, read wrangler.toml and the relevant src/entrypoint.ts, src/worker.ts, and src/index.ts files, then validate the configured main entrypoint, layer ownership, Durable Object binding/class, and route HTTP methods against the documented architecture. Keep the existing regression assertions while making these relationships fail when runtime structure changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@ARCHITECTURE.md`:
- Around line 11-14: Update the exact workflow trust logic in src/worker.ts to
require immutable SHA-based identity: validate workflow_sha and job_workflow_sha
in addition to the full workflow_ref, rather than trusting mutable branch or tag
refs alone. Update ARCHITECTURE.md lines 11-14 and 24-33 and CLAUDE.md lines 9
and 31-36 so their trust descriptions accurately state the SHA validation and
immutable source binding performed by src/worker.ts.
In `@CLAUDE.md`:
- Line 27: README의 운영 도구 설명과 실제 문서 내용을 정합화하세요. 각 명령(kpi:compute, smoke:check,
production:preflight, readiness:audit, acquisition:manifest/acquisition:audit,
security:evidence)의 필수 NOEMA_* 환경 변수를 README에 명령별로 추가하고, 기존 Worker 및 KPI 수집 예시와
구분해 문서화하세요. 실제 요구 변수를 확인할 수 없다면 해당 변수를 문서화한다고 주장하지 않도록 CLAUDE.md의 문장을 범위에 맞게
축소하세요.
---
Nitpick comments:
In `@docs/doctoring/architecture-trust-boundaries.md`:
- Around line 70-78: Update the Durable Object alarm semantics section to state
that automatic retries use exponential backoff and are limited to a maximum of
six attempts. Also document that handlers requiring recovery beyond those
retries must explicitly schedule a new alarm, while preserving the existing
at-least-once and stale-state validation guidance.
In `@test/architecture-documentation.test.ts`:
- Around line 5-35: Strengthen the architecture documentation tests beyond
keyword checks by asserting the runtime contract against actual configuration
and source ownership. In the existing tests, read wrangler.toml and the relevant
src/entrypoint.ts, src/worker.ts, and src/index.ts files, then validate the
configured main entrypoint, layer ownership, Durable Object binding/class, and
route HTTP methods against the documented architecture. Keep the existing
regression assertions while making these relationships fail when runtime
structure changes.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 4bd0e593-d123-4411-ad24-d5e917057839
📒 Files selected for processing (6)
ARCHITECTURE.mdCHANGELOG.mdCLAUDE.mdREADME.mddocs/doctoring/architecture-trust-boundaries.mdtest/architecture-documentation.test.ts
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@test/workflow-sha-trust.test.ts`:
- Around line 122-132: Extend the workflow trust tests around
expectWorkflowBlock to cover runtimeEnv without ALLOWED_WORKFLOW_SHA, asserting
it resolves with status 503 and message "Workflow trust configuration
unavailable". Keep the existing malformed-SHA case unchanged and exercise the
undefined binding branch explicitly.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: cee8500d-f924-4bb0-9314-7c44ed164834
📒 Files selected for processing (2)
src/worker.tstest/workflow-sha-trust.test.ts
seonghobae
changed the title
seonghobae
marked this pull request as ready for review
August 17, 2026 19:35
Contributor
|
Bugbot is not enabled for your account, so this pull request was not reviewed. Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs. |
This was referenced Aug 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Purpose
Maintain Noema's single canonical PRD/TRD/Architecture/ADR/UML/ERD/Test Strategy/Operability/licensing/traceability graph without reintroducing separately owned root README/CLAUDE/CHANGELOG content.
Current bounded ownership
This PR owns the canonical documentation graph and its documentation-contract tests only. Protected-main runtime/source, the customer-facing README/procedure integrated by #415, and readiness/operator documentation integrated by #413 are separate protected-main lanes.
The branch preserves current protected behavior rather than inventing stronger shipped claims:
ALLOWED_WORKFLOW_REF_PREFIXis documented as exact-full-ref behavior, while stronger immutable workflow-source binding is explicitly not claimed as shipped;docs/TEST_STRATEGY.mdand traceability close the canonical-documentation portion of issue quality(coverage): remove broad V8 ignore from credential-exchange security core #84 without claiming additional source changes;Test-first current-owner repair
Fresh exact-head application CI exposed stale documentation-contract assertions after governance PR #412 and operator/documentation PR #413 had already merged. Restoring those closed PRs to the active-owner table would have made the documentation less correct, so the tests were repaired instead of regressing the canonical graph.
c30648d648310568f0562c1232ab649dc4f8259echanges the documentation contracts to require only current open owners (docs: establish canonical product and trust-boundary documentation #71, feat(sandbox): restack patch-validator image on current main #407, feat(sandbox): build and verify patch-validator image #67), reject closed fix(governance): separate observed workflow evidence from target policy #412/docs: document readiness and surveillance semantics #413 as active-owner rows, and keep transient check state observation-scoped rather than timeless.e1a2aef6b9bdb621507de4be012fbde40de7e910reconcilesdocs/PRD.mdanddocs/TRACEABILITY.mdwith protected mainacf16c1e07f7b82659a26d42706212f2cc229882: merged fix(governance): separate observed workflow evidence from target policy #412 is protected governance-evidence implementation, merged docs: document readiness and surveillance semantics #413/docs: customer-facing README and relocated agent procedure #415 are protected documentation truth, while issue chore(governance): protect main and enforce release checks #27 remains the target-governance owner.Live-base convergence
Current exact head:
e1a2aef6b9bdb621507de4be012fbde40de7e910.Current protected main:
acf16c1e07f7b82659a26d42706212f2cc229882.The branch is a clean descendant of the current protected head (
behind_by=0) and changes exactly the canonical documentation/test surface. It does not modify protected runtime source, workflows, root README, contributor procedure, or readiness/operator documentation.Exact-head evidence
On unchanged head
e1a2aef6b9bdb621507de4be012fbde40de7e910:32060956407: success;32060956362: success;32060956231: success;CodeRabbit: success;The live organization ruleset requires the central Security Scan workflow on the default branch and has no bypass actor. No release, deployment, legal-clearance, certification, or acquisition-ready claim is made.