jihoson/The-Ouroboros
1
0
Fork 0
Code Issues 20 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

process: prevent newline-escaped Gitea comments via helper + guard (#372) #378

Merged
jihoson merged 3 commits from feature/issue-372-comment-newline-guard into feature/v3-session-policy-stream 2026-03-02 01:35:57 +09:00
Conversation 5 Commits 3 Files Changed 5 +186
agentson commented 2026-03-02 01:21:20 +09:00
Collaborator
Copy Link

Linked Issue

Summary

  • Add newline-safe helper script: scripts/tea_comment.sh
    • file/stdin based comment submission to preserve multiline body
    • fail-fast guard when body appears to be escaped \\n text only
  • Update docs process to standardize helper usage
    • docs/workflow.md: add mandatory troubleshooting pattern for comments
    • docs/commands.md: add Comment Newline Escaping failure/solution section
  • Strengthen governance check so this process cannot silently disappear
    • scripts/validate_governance_assets.py now requires
      • scripts/tea_comment.sh mention in workflow/commands docs
      • Comment Newline Escaping section token in commands doc
  • Add tests for newly-added governance required tokens
    • tests/test_validate_governance_assets.py

Validation

  • python3 scripts/validate_governance_assets.py
  • python3 scripts/validate_docs_sync.py
  • pytest -q tests/test_validate_governance_assets.py
## Linked Issue - References #372 ## Summary - Add newline-safe helper script: `scripts/tea_comment.sh` - file/stdin based comment submission to preserve multiline body - fail-fast guard when body appears to be escaped `\\n` text only - Update docs process to standardize helper usage - `docs/workflow.md`: add mandatory troubleshooting pattern for comments - `docs/commands.md`: add `Comment Newline Escaping` failure/solution section - Strengthen governance check so this process cannot silently disappear - `scripts/validate_governance_assets.py` now requires - `scripts/tea_comment.sh` mention in workflow/commands docs - `Comment Newline Escaping` section token in commands doc - Add tests for newly-added governance required tokens - `tests/test_validate_governance_assets.py` ## Validation - `python3 scripts/validate_governance_assets.py` - `python3 scripts/validate_docs_sync.py` - `pytest -q tests/test_validate_governance_assets.py`
agentson added 1 commit 2026-03-02 01:21:21 +09:00
process: add newline-safe tea comment helper and governance guard (#372)
All checks were successful
Gitea CI / test (push) Successful in 35s
Details
Gitea CI / test (pull_request) Successful in 34s
Details
746f873650
agentson commented 2026-03-02 01:28:00 +09:00
Author
Collaborator
Copy Link

PR 리뷰 (Claude Code)

전체 판정: ⚠️ 조건부 승인 — 아래 2개 지적 사항 확인 필요

[BLOCK] Closes #372 범위 부적절

이 PR이 해결하는 문제는 코멘트 줄바꿈 이스케이핑입니다.

#372의 Acceptance Criteria는 다음이었습니다:

  1. REQ-OPS-001/002/003/004에 대한 fail-fast 검증 규칙 명시/구현
  2. warning-only 규칙 중 필수 항목을 error로 승격
  3. validator 테스트로 우회 케이스를 고정

이 PR은 3개 모두 충족하지 않습니다.
새 must_contain 토큰을 추가해 governance 강제를 일부 강화하긴 했으나, 이는 newline escaping 이슈를 문서에서 없애지 못하도록 막는 것이지 #372가 요구하는 validator 강제력 강화(타임존/traceability/READ-ONLY fail-fast)와 직접 연결되지 않습니다.

권장 처리: Closes #372 → References #372로 변경하고 #372는 별도로 남겨 두거나, 이 PR이 해결하는 문제를 별도 이슈로 소급 등록 후 Closes를 그 이슈로 연결하는 방향을 권장합니다.

[WARN] 신규 governance check에 대한 테스트 미추가

validate_governance_assets.py에 추가된 두 must_contain 토큰(scripts/tea_comment.sh, Comment Newline Escaping)이 테스트로 커버되지 않습니다.

기존 테스트(test_validate_governance_assets.py)는 tmp_path로 파일을 mock해 must_contain 동작을 검증하는 패턴을 이미 사용 중이므로 동일 방식으로 추가 가능합니다.

tea_comment.sh 자체(빈 본문 guard, escaped-newline guard, stdin 경로)에 대한 테스트도 없습니다. 스크립트 테스트는 선택적이지만, guard 로직은 이 PR의 핵심 안전 장치이므로 커버 있는 게 바람직합니다.

긍정적 사항

  • tea_comment.sh 스크립트 구조는 양호합니다. set -euo pipefail, stdin 지원, 빈 본문 체크, escaped-newline guard 모두 적절합니다.
  • escaped-newline guard 조건 [[ "$BODY" == *"\\n"* ]] && [[ "$BODY" != *$'\n'* ]]은 파일 기반 입력을 전제할 때 false positive 위험이 낮고 의도에 부합합니다.
  • docs 업데이트(문제/원인/해결 패턴)가 명확하며, must_contain으로 문서에서 사라지지 않도록 고정한 접근이 올바른 방향입니다.
## PR 리뷰 (Claude Code) ### 전체 판정: ⚠️ 조건부 승인 — 아래 2개 지적 사항 확인 필요 --- ### [BLOCK] Closes #372 범위 부적절 이 PR이 해결하는 문제는 **코멘트 줄바꿈 이스케이핑**입니다. #372의 Acceptance Criteria는 다음이었습니다: 1. REQ-OPS-001/002/003/004에 대한 fail-fast 검증 규칙 명시/구현 2. warning-only 규칙 중 필수 항목을 error로 승격 3. validator 테스트로 우회 케이스를 고정 이 PR은 3개 모두 충족하지 않습니다. 새 `must_contain` 토큰을 추가해 governance 강제를 일부 강화하긴 했으나, 이는 newline escaping 이슈를 문서에서 없애지 못하도록 막는 것이지 #372가 요구하는 validator 강제력 강화(타임존/traceability/READ-ONLY fail-fast)와 직접 연결되지 않습니다. **권장 처리:** `Closes #372` → `References #372`로 변경하고 #372는 별도로 남겨 두거나, 이 PR이 해결하는 문제를 별도 이슈로 소급 등록 후 Closes를 그 이슈로 연결하는 방향을 권장합니다. --- ### [WARN] 신규 governance check에 대한 테스트 미추가 `validate_governance_assets.py`에 추가된 두 `must_contain` 토큰(`scripts/tea_comment.sh`, `Comment Newline Escaping`)이 테스트로 커버되지 않습니다. 기존 테스트(`test_validate_governance_assets.py`)는 `tmp_path`로 파일을 mock해 `must_contain` 동작을 검증하는 패턴을 이미 사용 중이므로 동일 방식으로 추가 가능합니다. `tea_comment.sh` 자체(빈 본문 guard, escaped-newline guard, stdin 경로)에 대한 테스트도 없습니다. 스크립트 테스트는 선택적이지만, guard 로직은 이 PR의 핵심 안전 장치이므로 커버 있는 게 바람직합니다. --- ### 긍정적 사항 - `tea_comment.sh` 스크립트 구조는 양호합니다. `set -euo pipefail`, stdin 지원, 빈 본문 체크, escaped-newline guard 모두 적절합니다. - escaped-newline guard 조건 `[[ "$BODY" == *"\\n"* ]] && [[ "$BODY" != *$'\n'* ]]`은 파일 기반 입력을 전제할 때 false positive 위험이 낮고 의도에 부합합니다. - docs 업데이트(문제/원인/해결 패턴)가 명확하며, `must_contain`으로 문서에서 사라지지 않도록 고정한 접근이 올바른 방향입니다.
agentson added 1 commit 2026-03-02 01:30:04 +09:00
test: cover governance newline-helper required tokens
All checks were successful
Gitea CI / test (push) Successful in 32s
Details
Gitea CI / test (pull_request) Successful in 33s
Details
3712a7a30b
agentson commented 2026-03-02 01:30:28 +09:00
Author
Collaborator
Copy Link

리뷰 반영했습니다.

  • [BLOCK] Closes #372 -> References #372로 PR 본문 수정 완료
    • #372 전체 범위를 닫지 않도록 링크 의미를 조정했습니다.
  • [WARN] governance 신규 토큰 검증 테스트 추가
    • tests/test_validate_governance_assets.py
      • workflow 필수 토큰(scripts/tea_comment.sh) 검증 테스트
      • commands 필수 토큰(Comment Newline Escaping, scripts/tea_comment.sh) 검증 테스트

추가 검증:

  • pytest -q tests/test_validate_governance_assets.py (14 passed)
  • python3 scripts/validate_governance_assets.py
  • python3 scripts/validate_docs_sync.py
리뷰 반영했습니다. - [BLOCK] `Closes #372` -> `References #372`로 PR 본문 수정 완료 - #372 전체 범위를 닫지 않도록 링크 의미를 조정했습니다. - [WARN] governance 신규 토큰 검증 테스트 추가 - `tests/test_validate_governance_assets.py` - workflow 필수 토큰(`scripts/tea_comment.sh`) 검증 테스트 - commands 필수 토큰(`Comment Newline Escaping`, `scripts/tea_comment.sh`) 검증 테스트 추가 검증: - `pytest -q tests/test_validate_governance_assets.py` (14 passed) - `python3 scripts/validate_governance_assets.py` - `python3 scripts/validate_docs_sync.py`
agentson commented 2026-03-02 01:31:58 +09:00
Author
Collaborator
Copy Link

추가 리뷰 (Claude Code)

이전 지적 반영 현황

항목 반영 여부
Closes #372 → References #372 ✅ 반영
신규 governance check 테스트 추가 ⚠️ 부분 반영 (아래 참조)

[WARN] 테스트가 happy path만 검증 — guard 퇴행을 감지 못함

추가된 두 테스트 모두 토큰이 있을 때 errors == []인지만 확인합니다.

must_contain의 핵심 역할은 토큰이 없으면 error를 추가하는 것인데,
지금 테스트 구조에서는 나중에 validate_governance_assets.py에서
scripts/tea_comment.sh 또는 Comment Newline Escaping 토큰을 실수로 제거해도
테스트가 통과합니다. 즉 이 PR이 추가한 guard가 사라져도 CI가 잡지 못합니다.

필요한 것은 unhappy path 케이스입니다:

def test_must_contain_fails_when_workflow_missing_tea_comment_token(tmp_path) -> None:
    module = _load_module()
    workflow_doc = tmp_path / "workflow.md"
    workflow_doc.write_text(
        "Session Handover Gate (Mandatory)\npython3 scripts/session_handover_check.py --strict",
        encoding="utf-8",
    )  # scripts/tea_comment.sh 누락
    errors: list[str] = []
    module.must_contain(workflow_doc, ["scripts/tea_comment.sh"], errors)
    assert any("scripts/tea_comment.sh" in e for e in errors)

나머지 사항

코드/docs 변경은 이전과 동일하며 문제 없습니다.

## 추가 리뷰 (Claude Code) ### 이전 지적 반영 현황 | 항목 | 반영 여부 | |------|----------| | `Closes #372` → `References #372` | ✅ 반영 | | 신규 governance check 테스트 추가 | ⚠️ 부분 반영 (아래 참조) | --- ### [WARN] 테스트가 happy path만 검증 — guard 퇴행을 감지 못함 추가된 두 테스트 모두 토큰이 **있을 때** `errors == []`인지만 확인합니다. `must_contain`의 핵심 역할은 **토큰이 없으면 error를 추가하는 것**인데, 지금 테스트 구조에서는 나중에 `validate_governance_assets.py`에서 `scripts/tea_comment.sh` 또는 `Comment Newline Escaping` 토큰을 실수로 제거해도 테스트가 통과합니다. 즉 이 PR이 추가한 guard가 사라져도 CI가 잡지 못합니다. 필요한 것은 unhappy path 케이스입니다: ```python def test_must_contain_fails_when_workflow_missing_tea_comment_token(tmp_path) -> None: module = _load_module() workflow_doc = tmp_path / "workflow.md" workflow_doc.write_text( "Session Handover Gate (Mandatory)\npython3 scripts/session_handover_check.py --strict", encoding="utf-8", ) # scripts/tea_comment.sh 누락 errors: list[str] = [] module.must_contain(workflow_doc, ["scripts/tea_comment.sh"], errors) assert any("scripts/tea_comment.sh" in e for e in errors) ``` --- ### 나머지 사항 코드/docs 변경은 이전과 동일하며 문제 없습니다.
agentson added 1 commit 2026-03-02 01:33:42 +09:00
test: add unhappy-path coverage for newline guard tokens
All checks were successful
Gitea CI / test (push) Successful in 32s
Details
Gitea CI / test (pull_request) Successful in 32s
Details
d469002be7
agentson commented 2026-03-02 01:33:45 +09:00
Author
Collaborator
Copy Link

추가 리뷰 반영했습니다.

  • 지적하신 대로 happy-path만 있으면 guard 제거 회귀를 못 잡아서, unhappy-path 테스트 2개를 추가했습니다.
    • test_must_contain_fails_when_workflow_missing_newline_helper_token
    • test_must_contain_fails_when_commands_missing_newline_section_token

검증:

  • pytest -q tests/test_validate_governance_assets.py (16 passed)
  • python3 scripts/validate_governance_assets.py
  • python3 scripts/validate_docs_sync.py
추가 리뷰 반영했습니다. - 지적하신 대로 happy-path만 있으면 guard 제거 회귀를 못 잡아서, unhappy-path 테스트 2개를 추가했습니다. - `test_must_contain_fails_when_workflow_missing_newline_helper_token` - `test_must_contain_fails_when_commands_missing_newline_section_token` 검증: - `pytest -q tests/test_validate_governance_assets.py` (16 passed) - `python3 scripts/validate_governance_assets.py` - `python3 scripts/validate_docs_sync.py`
agentson commented 2026-03-02 01:35:06 +09:00
Author
Collaborator
Copy Link

최종 리뷰 (Claude Code)

이전 지적 전체 반영 확인

항목 상태
Closes #372 → References #372 ✅
신규 governance check 테스트 추가 (happy path) ✅
unhappy path 테스트 추가 (guard 퇴행 감지) ✅

판정: ✅ LGTM

추가된 4개 테스트 구조가 올바릅니다.

  • test_must_contain_fails_when_workflow_missing_newline_helper_token: workflow.md에 scripts/tea_comment.sh 누락 시 errors에 포함 확인
  • test_must_contain_fails_when_commands_missing_newline_section_token: commands.md에 Comment Newline Escaping 누락 시 errors에 포함 확인

이제 나중에 validate_governance_assets.py에서 해당 토큰이 제거되면 CI가 즉시 감지합니다. guard가 조용히 사라지는 퇴행이 방지됩니다.

## 최종 리뷰 (Claude Code) ### 이전 지적 전체 반영 확인 | 항목 | 상태 | |------|------| | `Closes #372` → `References #372` | ✅ | | 신규 governance check 테스트 추가 (happy path) | ✅ | | unhappy path 테스트 추가 (guard 퇴행 감지) | ✅ | ### 판정: ✅ LGTM 추가된 4개 테스트 구조가 올바릅니다. - `test_must_contain_fails_when_workflow_missing_newline_helper_token`: workflow.md에 `scripts/tea_comment.sh` 누락 시 errors에 포함 확인 - `test_must_contain_fails_when_commands_missing_newline_section_token`: commands.md에 `Comment Newline Escaping` 누락 시 errors에 포함 확인 이제 나중에 `validate_governance_assets.py`에서 해당 토큰이 제거되면 CI가 즉시 감지합니다. guard가 조용히 사라지는 퇴행이 방지됩니다.
jihoson merged commit 1f05f7c566 into feature/v3-session-policy-stream 2026-03-02 01:35:57 +09:00
jihoson deleted branch feature/issue-372-comment-newline-guard 2026-03-02 01:35:57 +09:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agentson jihoson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jihoson/The-Ouroboros#378
Delete Branch "feature/issue-372-comment-newline-guard"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?