docs(document-haness): 관문의 종료 코드 — CASE 한 편을 근거까지 잇고 런 원장을 남긴다
이 저장소 자신의 검사 층을 대상으로 삼았다. 파이프 뒤의 $? 를 읽고 검사기 열넷이 전부 --help 를 받는다고 적었다가, 파이프를 걷고 다시 재니 둘이 exit 1 이었던 일. 관찰·원인·조치가 한 사건으로 닫히고 조치가 capture-evidence.py 다. 증거 여덟 건은 전부 그 도구가 수집했다. proves/doesNotProve 로 「이 출력이 뒷받침하는 것」과 「뒷받침하지 못하는 것」을 증거 쪽에 적어 두었다 — 본문이 그 경계를 넘었는지 대조할 것이 생긴다. 함께 올린 Question 은 「검사할 것이 없을 때 관문은 무엇을 내야 하는가」다. 현상은 재현했고 조치가 없어 Case 로 올리지 않았다. 조치 없이 쓰면 관찰만 있고 결과가 없는 글이 된다. 런 원장은 단계마다 서브에이전트를 하나씩 띄운 기록이다. 넷이 실제로 무언가를 잡았다 — S3 이 「argparse 를 쓰지 않는 셋」이 증거 원문과 어긋나는 것을(넷이다), S1 이 그 뿌리를 SSOT·앵커·증거 메타에서, S5 가 「증거 여섯 개」가 frontmatter 의 다섯과 어긋나는 것을, S6 이 계약의 「한 번밖에 안 써서」가 메타 여덟 건과 어긋나는 것을. 셋 다 한 세션이 일곱 단계를 겸했으면 안 나왔다. 내가 쓴 글을 내가 다시 읽는 것이기 때문이다. style_profile 은 exit 1 로 그대로 적었다. 관문이 아니라 측정이고, 돌리지 않은 값을 0 으로 적는 것이 이 원장이 막으려는 바로 그것이다. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q4vKjQo9KKBBokzxqXLCfk
This commit is contained in:
DongHyeonka
co-authored by
Claude Opus 5
Claude Opus 5
parent
cf3996711f
commit
230e1b20cb
@@ -0,0 +1,233 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"runId": "2026-09-10-1033",
|
||||
"project": "document-haness",
|
||||
"record": "docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"startedAt": "2026-09-10T10:33:45+09:00",
|
||||
"finishedAt": "2026-09-10T11:00:39+09:00",
|
||||
"stages": [
|
||||
{
|
||||
"id": "S1",
|
||||
"name": "코드베이스 → SSOT",
|
||||
"skill": "analyzing-codebase-for-tech-log",
|
||||
"runBy": "subagent",
|
||||
"status": "DONE",
|
||||
"skipReason": "",
|
||||
"skillEcho": "Do not turn inference into observation in the final document.",
|
||||
"inputs": [
|
||||
"docs/document-haness/final/document.md",
|
||||
"docs/document-haness/final/evidence/raw/**",
|
||||
"docs/document-haness/final/evidence/meta/**"
|
||||
],
|
||||
"outputs": [
|
||||
"docs/document-haness/final/document.md",
|
||||
"docs/document-haness/final/evidence/meta/argparse-absent-scripts.json",
|
||||
"docs/document-haness/final/evidence/meta/what-the-three-print-for-help.json",
|
||||
"docs/document-haness/tech-log-studio/tech-log-tree.json"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"cmd": "python3 scripts/verify-project-layout.py document-haness",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/build-tech-log-tree.py document-haness",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/verify-tech-log-tree.py document-haness",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs document-haness --repo",
|
||||
"exit": 0
|
||||
}
|
||||
],
|
||||
"notes": "대조 모드다. 분석을 새로 하지 않고 SSOT 가 증거 원문과 어긋나는지만 봤다. S3 이 올린 어긋남 하나가 실물이었다 — 증거 정본 argparse-absent-scripts.txt 의 「ARGPARSE 없음」이 4줄인데 SSOT 는 셋이라고 적었다. 「argparse 가 없는 것(넷)」과 「--help 를 위치 인자로 먹는 것(셋)」을 한 숫자로 섞은 것이다. SSOT 네 곳(:155 절 제목 · :157 · :176 · §9)을 고치고, 절 제목이 바뀌어 앵커를 가리키는 세 곳(계약 2 · 기록 frontmatter 1)을 함께 고쳤다. 증거 메타 둘의 proves·doesNotProve 도 같은 오산을 담고 있어 고쳤다 — 그것은 사람이 적은 주장이다. exitCode·sha256·bytes·command 는 실행이 적은 값이라 안 건드렸고, raw 원문은 한 글자도 안 건드렸다(메타 8건의 sha256 을 다시 계산해 원문과 일치 확인). runs/.../stage/S3-before.md 는 과거 사본이라 옛 앵커를 그대로 두었다. 그 밖에 §1~§9 의 인용 블록 다섯을 raw 와 diff 로 대조했고 §7 의 원장 인용이 runs/virtualization/2026-09-09-1052/run.json:78 에 실재하는 것까지 확인했다. 오케스트레이터가 증거 원문과 코드로 다시 세어 넷인 것을 독립으로 확인했다. 판단이 필요해 안 고친 것 둘 — guards/ 증거 둘을 인용하는 기록이 없고(warn 2건), sourceRepository.path 가 worktree 가 아니라 원본 경로를 가리킨다(verified 칸이 사유를 적는다)."
|
||||
},
|
||||
{
|
||||
"id": "S2",
|
||||
"name": "SSOT → 분해 계약",
|
||||
"skill": "deriving-tech-log-root-tree",
|
||||
"runBy": "orchestrator",
|
||||
"status": "SKIPPED",
|
||||
"skipReason": "이 글감이 tech-log-tree.json 에 이미 PROMOTE · dispositionReview CONFIRMED 로 있다 (candidates[DH-C01], target=case:exit-code-read-behind-a-pipe). 분해를 다시 하지 않았다.",
|
||||
"skillEcho": "",
|
||||
"inputs": [
|
||||
"docs/document-haness/final/document.md",
|
||||
"docs/document-haness/tech-log-studio/tech-log-tree.json"
|
||||
],
|
||||
"outputs": [
|
||||
"docs/document-haness/tech-log-studio/tech-log-tree.json"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"cmd": "python3 scripts/build-tech-log-tree.py document-haness",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/verify-tech-log-tree.py document-haness",
|
||||
"exit": 0
|
||||
}
|
||||
],
|
||||
"notes": "build 는 파생 칸(file·publication·status·ssotSha256)만 다시 채운다. 사람이 적은 칸은 그대로다."
|
||||
},
|
||||
{
|
||||
"id": "S3",
|
||||
"name": "글감 → 기록",
|
||||
"skill": "writing-tech-log-records",
|
||||
"runBy": "subagent",
|
||||
"status": "DONE",
|
||||
"skipReason": "",
|
||||
"skillEcho": "**옮겨 적었다고 확인한 것이 아니다.** 앞선 기록에서 코드를 가져오거나 기억으로 경로를 쓰면",
|
||||
"inputs": [
|
||||
"docs/document-haness/tech-log-studio/tech-log-tree.json",
|
||||
"docs/document-haness/final/document.md",
|
||||
"runs/document-haness/2026-09-10-1033/stage/S3-before.md"
|
||||
],
|
||||
"outputs": [
|
||||
"docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"cmd": "python3 scripts/studio-body.py docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md -o /tmp/s3-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node --experimental-transform-types .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/s3-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs document-haness --repo",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/verify-tech-log-tree.py document-haness",
|
||||
"exit": 0
|
||||
}
|
||||
],
|
||||
"notes": "기록은 이미 있었고 서브에이전트가 계약·SSOT 와 대조해 세 곳을 고쳤다. (1) 요약 칸의 백틱 — 평문으로 렌더링되는 칸이다. (2) 요약이 「계약 문서에까지 들어갔다」고 적었는데 SSOT 는 「확인 등급 확인함으로 적었다」까지만 말한다. SSOT 가 뒷받침하는 문장으로 바꿨다. (3) 본문이 「열넷 중 셋이 argparse 를 쓰지 않는다」로 시작하면서 바로 아래 표에 「없음」을 넷 적어 두었다. 증거 정본 argparse-absent-scripts.txt 의 「ARGPARSE 없음」이 4줄이므로 표가 맞고 문장이 틀렸다 — 셋→넷, 남은 둘→남은 셋으로 고쳤다. 오케스트레이터가 증거 원문과 코드로 다시 세어 넷인 것을 확인했다. 같은 오산이 SSOT·계약·증거 메타에 그대로 있다는 것을 서브에이전트가 크게 적어 올렸고, SSOT 를 고치는 것은 자기 단계 밖이라 손대지 않았다 — S1 로 돌렸다. check_prose 경고 2건(CASE·POSIX 약어)은 남겼다. CASE 는 frontmatter 의 kind 값이고 POSIX 는 SSOT 가 쓰는 표준 명칭이라 풀어 쓰면 보호 구간을 건드린다."
|
||||
},
|
||||
{
|
||||
"id": "S4",
|
||||
"name": "기록 → 그림",
|
||||
"skill": "technical-visualizer",
|
||||
"runBy": "orchestrator",
|
||||
"status": "SKIPPED",
|
||||
"skipReason": "그림이 필요 없다. 세 관문 중 셋째에 걸린다 — 본문의 「왜 그 둘만인가」 절이 argparse 유무와 --help 결과를 표 하나로 답하고 있어, 같은 것을 그림으로 다시 그리면 옆 문단이 이미 말한 것을 되풀이한다. 계약의 이 노드에도 assets 가 없다.",
|
||||
"skillEcho": "",
|
||||
"inputs": [],
|
||||
"outputs": [],
|
||||
"gates": [],
|
||||
"notes": "이 프로젝트의 final/assets 는 비어 있다. check-figure-text.py 와 check-figure-overlap.py 는 볼 그림이 없어 돌리지 않았다."
|
||||
},
|
||||
{
|
||||
"id": "S5",
|
||||
"name": "AI 티 제거",
|
||||
"skill": "rewriting-technical-prose-naturally",
|
||||
"runBy": "subagent",
|
||||
"status": "DONE",
|
||||
"skipReason": "",
|
||||
"skillEcho": "| Sentences are all short and choppy | Rejoin with `~기 때문에`, `~다 보니`, `~어서`; break only where the subject changes |",
|
||||
"inputs": [
|
||||
"docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"runs/document-haness/2026-09-10-1033/stage/S5-before.md"
|
||||
],
|
||||
"outputs": [
|
||||
"docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"cmd": "node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/rewriting-technical-prose-naturally/scripts/style_profile.mjs docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 1
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/studio-body.py docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md -o /tmp/s5-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node --experimental-transform-types .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/s5-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs document-haness --repo",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/check-preservation.py runs/document-haness/2026-09-10-1033/stage/S5-before.md docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
}
|
||||
],
|
||||
"notes": "서브에이전트가 아홉 곳을 고쳤다. 전부 문장을 잇거나 문단 순서를 옮긴 것이고 삭제한 문장도 새로 쓴 문장도 없다(68문장 → 63문장). check-preservation.py 가 「보호 구간 변화 0건 · 유보 감소 0종」으로 확인했다 — 윤문이 수치·코드·인용·URL 을 건드리지 않았고 유보 표현도 안 지웠다는 뜻이다. style_profile.mjs 는 exit 1 로 그대로 적는다. 관문이 아니라 측정이고 문서 계약이 이것에만 「error 0」을 안 붙였다. 이유 연결어미는 5.9 → 9.5 로 기준 안에 들어왔고 문장 평균 길이는 41.6 → 45 로 기준(48~75) 밖에 남았다. 서브에이전트가 남은 짧은 문장 22개를 전부 열어 보고 재현 조건 단계·수치 한 줄·코드로 넘기는 도입·정의 한 줄·방향 전환이라 잇지 않았다고 적었다. 수치를 맞추려고 문장을 넣지 말라는 것이 스킬의 규칙이다. 서브에이전트가 사실 어긋남 하나를 올렸다 — 본문이 「이 기록의 증거 여섯 개」라고 적었는데 frontmatter 의 evidence 는 다섯이다. 수치는 보호 구간이라 S5 가 못 고친다고 판단해 넘겼고, 오케스트레이터가 frontmatter 를 세어 확인한 뒤 다섯으로 고쳤다. check-preservation 은 이 고침을 못 잡는다 — 한글 수사는 아라비아 숫자가 아니라서 보호 구간 비교에 안 걸린다. 이 검사기의 알려진 한계다."
|
||||
},
|
||||
{
|
||||
"id": "S6",
|
||||
"name": "일한 사람의 목소리",
|
||||
"skill": "writing-as-the-person-who-did-it",
|
||||
"runBy": "subagent",
|
||||
"status": "DONE",
|
||||
"skipReason": "",
|
||||
"skillEcho": "고치는 방법은 하나뿐이다. **자료에 남아 있는 사람의 흔적을 찾아서 제자리에 놓는다.**",
|
||||
"inputs": [
|
||||
"docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"docs/document-haness/final/document.md",
|
||||
"docs/document-haness/tech-log-studio/tech-log-tree.json",
|
||||
"docs/document-haness/final/evidence/meta/*.json",
|
||||
"scripts/capture-evidence.py",
|
||||
"runs/document-haness/2026-09-10-1033/run.json",
|
||||
"runs/document-haness/2026-09-10-1033/stage/S6-before.md"
|
||||
],
|
||||
"outputs": [
|
||||
"docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md"
|
||||
],
|
||||
"gates": [
|
||||
{
|
||||
"cmd": "node .agents/skills/writing-as-the-person-who-did-it/scripts/check_voice.mjs docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/rewriting-technical-prose-naturally/scripts/check_prose.mjs --warn docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/studio-body.py docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md -o /tmp/s6-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node --experimental-transform-types .agents/skills/writing-tech-log-records/scripts/check_body.mjs /tmp/s6-body.md",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "node .agents/skills/writing-tech-log-records/scripts/check_evidence.mjs document-haness --repo",
|
||||
"exit": 0
|
||||
},
|
||||
{
|
||||
"cmd": "python3 scripts/check-preservation.py runs/document-haness/2026-09-10-1033/stage/S6-before.md docs/document-haness/tech-log-studio/pipeline-gate-exit-codes/case/case-exit-code-read-behind-a-pipe.md",
|
||||
"exit": 0
|
||||
}
|
||||
],
|
||||
"notes": "흔적 있음. 두 곳을 넣었고 둘 다 근거를 파일과 칸으로 댔다. (A) 「왜 그 둘만인가」 절에 이 런이 겪은 어긋남을 그 대목에 놓았다 — 두 숫자를 섞어 넷을 셋으로 적었고 그것이 분석 문서 네 곳과 증거 메타 둘에 실렸으며 증거 원문에서 줄을 다시 세어 고쳤다는 것. 근거는 이 원장의 S1·S3 notes 다. (B) 「손으로 적지 못하게 했다」 절에 도구를 쓴 사람의 말을 옮겼다 — scripts/capture-evidence.py 의 docstring :5 와 :9 다. 기록이 기능만 적고 목표와 이유는 안 적던 자리다. 인용부호나 백틱으로 감싸지 않고 평문으로 녹였다 — check-preservation 이 새로 생긴 인라인코드와 「」 직접인용을 「새로생김」으로 세기 때문이다. 낱말은 docstring 그대로다. 안 넣은 것도 적었다. 「처음에는」·「고민 끝에」·「놀랍게도」는 자료에 없어 한 건도 안 썼고, 커밋 메시지는 capture-evidence.py 가 아직 untracked 라 흔적이 없다 — 찾아봤고 없었다. 이미 있던 사람의 흔적 셋(같은 착각이 한 번 더 났다 · 셸 래퍼도 됐지만 · 처음 판에서는 이 도구도 인자를 잘못 먹었다)에는 손대지 않았다. 서브에이전트가 계약의 어긋남 하나를 올렸다 — candidates[DH-C03].reason 이 「한 번밖에 안 써서」라고 적는데 이 도구가 적은 메타가 여덟 건이다. 자료와 어긋나 그 문장을 근거로 못 쓴다고 판단하고 안 넣었다. 오케스트레이터가 메타를 세어 확인한 뒤 계약을 「이 저장소 하나에서만 써서 … 실행 여덟 건이 전부 이 프로젝트의 증거 수집이고 다른 프로젝트나 브라우저 캡처에 걸어 본 적이 없다」로 고쳤다."
|
||||
},
|
||||
{
|
||||
"id": "S7",
|
||||
"name": "Studio 저장",
|
||||
"skill": "publishing-tech-log-to-studio",
|
||||
"runBy": "orchestrator",
|
||||
"status": "SKIPPED",
|
||||
"skipReason": "Studio 반입을 요청받지 않았다. 이 배치에서 Studio 브라우저 세션은 통합 세션 A 가 소유하고, 게시 권한이 저장 권한과 분리돼 있지 않아 무인 저장이 막혀 있다 (A-studio-change-requests.md 의 CR-001). 화면을 열지 않았다.",
|
||||
"skillEcho": "",
|
||||
"inputs": [],
|
||||
"outputs": [],
|
||||
"gates": [],
|
||||
"notes": "기록 frontmatter 의 id 와 studio 는 비어 있다. 저장한 적이 없다는 뜻이고 그대로 둔다."
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
id:
|
||||
kind: CASE
|
||||
slug: exit-code-read-behind-a-pipe
|
||||
title: 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
topic: pipeline-gate-exit-codes
|
||||
topicName: 관문의 종료 코드
|
||||
project: document-haness
|
||||
status: 게시 전
|
||||
studio: ""
|
||||
lastVerifiedOn: 2026-09-10
|
||||
source:
|
||||
- final/document.md#§2-관찰한-것
|
||||
- final/document.md#§3-파이프-뒤의-종료-코드
|
||||
- final/document.md#§4-다시-잰-값
|
||||
- final/document.md#§5-argparse-를-쓰지-않는-셋
|
||||
- final/document.md#§8-종료-코드를-손으로-적을-수-없게-만든다
|
||||
sourceRevision: 43e1aadef077ad93c30495df428ee3a71dd73f4a
|
||||
evidence:
|
||||
- ../../../final/evidence/raw/exit-code-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-without-a-pipe.txt
|
||||
- ../../../final/evidence/raw/argparse-absent-scripts.txt
|
||||
- ../../../final/evidence/raw/what-the-three-print-for-help.txt
|
||||
---
|
||||
|
||||
# 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
|
||||
`scripts/` 의 검사기 열넷에 `--help` 를 돌려 전부 종료 코드 0 을 받았다. 두 세션이 각자
|
||||
같은 값을 얻어 계약 문서에까지 「14개 전부 `--help` 가 종료 코드 0」으로 들어갔다. 값은
|
||||
검사기가 아니라 재는 방법이 만든 것이었다. 파이프를 걷어 내고 다시 재니 둘이 `exit 1` 이다.
|
||||
|
||||
## 관계
|
||||
|
||||
- **검사할 것이 없을 때 관문은 무엇을 내야 하는가**
|
||||
이 사건에서 `audit-records.py --help` 가 「문제 없음」을 찍으면서 그 물음이 열렸다.
|
||||
`--help` 라는 이름의 프로젝트에는 검사할 기록이 하나도 없어 그대로 통과했다.
|
||||
|
||||
## 문제
|
||||
|
||||
관문은 종료 코드로 말한다. 단계 계약이 「관문은 종료 코드가 0 이어야 지난 것이다」 라고
|
||||
적었고, 런 원장 run.json 의 stages[].gates[].exit 에 그 값이 남는다. 사람이 셸에서 그 값을
|
||||
읽어 옮겨 적는다.
|
||||
|
||||
--help 하나를 잰 것뿐인데 값이 두 번 틀렸다. 관문 결과 전부가 같은 방법으로 적히고 있다.
|
||||
|
||||
## 결론
|
||||
|
||||
리비전 43e1aad 의 scripts/*.py 열넷 중 열둘이 --help 에 exit 0,
|
||||
build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다.
|
||||
exit 0 이 usage 가 나왔다는 뜻은 아니다 — audit-records.py 는 --help 를 프로젝트
|
||||
이름으로 받아 검사하고 통과시킨다.
|
||||
|
||||
값을 틀리게 만든 것은 셸의 동작 둘이다. 파이프의 종료 코드 변수는 마지막 명령을 가리키고,
|
||||
명령 치환은 그 변수를 덮어쓴다. 둘 다 정의된 동작이라 셸이 경고하지 않는다.
|
||||
|
||||
조치로 scripts/capture-evidence.py 를 만들었다. 명령을 subprocess 로 직접 돌리고 그
|
||||
프로세스의 반환값을 그대로 메타에 적는다. 종료 코드를 인자로 받지 않으므로 손으로 적을
|
||||
경로가 없다.
|
||||
|
||||
## 검증 환경
|
||||
|
||||
python 3.12.3 · node v24.14.0 · bash 5.2.21(1)-release · Linux.
|
||||
대상 저장소 document-haness 리비전 43e1aadef077ad93c30495df428ee3a71dd73f4a.
|
||||
측정은 그 커밋에서 갈라진 worktree dh-B 에서 했고, 그 시점 작업 트리에는
|
||||
capture-evidence.py 가 더해져 있어 증거 메타의 sourceDirty 가 true 다.
|
||||
측정 대상 열넷은 git ls-tree 로 그 커밋의 목록만 골라 냈다.
|
||||
|
||||
## 재현 조건
|
||||
|
||||
1. document-haness 를 43e1aad 로 체크아웃한다.
|
||||
2. 파이프를 끼고 잰다 — 반복문 안에서 python3 출력을 head 로 넘기고 그다음 줄에서 $? 를 읽는다.
|
||||
3. 열넷이 전부 exit=0 으로 나오는 것을 본다.
|
||||
4. 파이프를 걷고 out=$(...) 다음 줄에서 code=$? 로 받아 다시 잰다.
|
||||
5. build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit=1 로 갈리는 것을 본다.
|
||||
|
||||
## 본문
|
||||
|
||||
<!-- body:start -->
|
||||
|
||||
## 두 번 같은 값이 나왔다
|
||||
|
||||
검사기 목록을 만들려고 열넷에 `--help` 를 돌렸다. 출력이 길어서 `head` 로 잘랐다.
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
timeout 60 python3 $s --help 2>&1 | head -30 >/dev/null
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
열넷이 전부 `exit=0` 이었다.
|
||||
|
||||
```
|
||||
audit-records.py exit=0
|
||||
build-tech-log-tree.py exit=0
|
||||
check-figure-overlap.py exit=0
|
||||
check-figure-text.py exit=0
|
||||
fold-analysis-into-final.py exit=0
|
||||
fold-studio-contract-into-index.py exit=0
|
||||
preview-figure.py exit=0
|
||||
studio-body.py exit=0
|
||||
techlog.py exit=0
|
||||
verify-pipeline-run.py exit=0
|
||||
verify-pipeline.py exit=0
|
||||
verify-project-layout.py exit=0
|
||||
verify-refactor-work-item.py exit=0
|
||||
verify-tech-log-tree.py exit=0
|
||||
```
|
||||
|
||||
이 저장소를 함께 조사한 다른 세션도 같은 값을 얻어 「`scripts/*.py` 14개 전부 `--help` 가
|
||||
종료 코드 0 으로 돌아온다」 를 확인 등급 **확인함**으로 적었다. 두 사람이 같은 값을 얻었으니
|
||||
맞는 값처럼 보였다.
|
||||
|
||||
## 값을 만든 것은 셸이다
|
||||
|
||||
파이프라인의 `$?` 는 **마지막** 명령의 종료 코드다. `head` 는 언제나 성공하므로 앞의
|
||||
`python3` 가 무엇을 반환하든 `$?` 는 0 이 된다.
|
||||
|
||||
```bash
|
||||
set +o pipefail
|
||||
false | head -1; echo "false | head -1 -> exit=$?"
|
||||
false; echo "false -> exit=$?"
|
||||
```
|
||||
|
||||
```
|
||||
false | head -1 -> exit=0
|
||||
false -> exit=1
|
||||
bash 5.2.21(1)-release
|
||||
```
|
||||
|
||||
POSIX 셸의 정의된 동작이고 이 셸의 특이점이 아니다. `pipefail` 을 켜거나
|
||||
`${PIPESTATUS[0]}` 를 읽으면 앞 명령의 값을 얻는다.
|
||||
|
||||
같은 착각이 한 번 더 났다. 파이프를 걷어 내고 다시 잴 때 이렇게 썼다.
|
||||
|
||||
```bash
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
echo "$(basename $s) exit=$?"
|
||||
```
|
||||
|
||||
명령 치환 `$(basename $s)` 가 먼저 실행되면서 `$?` 를 덮어썼다. 그래서 두 번째 측정도
|
||||
열넷 전부 0 이었다. `code=$?` 를 명령 바로 다음 줄에 두고서야 값이 갈렸다.
|
||||
|
||||
## 다시 잰 값
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
두 측정의 차이는 두 줄뿐이다. 잰 것은 `--help` 하나뿐이라 나머지 열둘이 다른 인자에서
|
||||
어떻게 도는지는 이 값이 말해 주지 않는다.
|
||||
|
||||
```
|
||||
2c2
|
||||
< build-tech-log-tree.py exit=0
|
||||
---
|
||||
> build-tech-log-tree.py exit=1
|
||||
13c13
|
||||
< verify-refactor-work-item.py exit=0
|
||||
---
|
||||
> verify-refactor-work-item.py exit=1
|
||||
```
|
||||
|
||||
## 왜 그 둘만인가
|
||||
|
||||
열넷 중 셋이 `argparse` 를 쓰지 않는다.
|
||||
|
||||
| 스크립트 | `argparse` | `--help` |
|
||||
|---|---|---|
|
||||
| `audit-records.py` | 없음 | `exit 0` — 「문제 없음」 |
|
||||
| `build-tech-log-tree.py` | 없음 | `exit 1` |
|
||||
| `techlog.py` | 없음 | `exit 0` — CLI 가 아니라 인자를 안 읽는다 |
|
||||
| `verify-refactor-work-item.py` | 없음 | `exit 1` |
|
||||
| 나머지 열 | 있음 | `exit 0` — usage |
|
||||
|
||||
남은 둘은 `--help` 를 옵션이 아니라 위치 인자로 먹는다. `audit-records.py` 는 그것을
|
||||
프로젝트 이름으로 받아 「문제 없음」을 찍고, `build-tech-log-tree.py` 와
|
||||
`verify-refactor-work-item.py` 는 그 이름의 파일을 못 찾아 실패한다.
|
||||
|
||||
```
|
||||
$ python3 scripts/audit-records.py --help
|
||||
|
||||
--help — 기록 0건 · 원문 0 · 메타 0 · 렌더 0
|
||||
문제 없음
|
||||
|
||||
합계 0건
|
||||
exit=0
|
||||
|
||||
$ python3 scripts/build-tech-log-tree.py --help
|
||||
--help: tech-log-tree.json 이 없다. 글감을 먼저 적는다
|
||||
exit=1
|
||||
|
||||
$ python3 scripts/verify-refactor-work-item.py --help
|
||||
REFACTOR WORK ITEM VERIFICATION: FAIL
|
||||
- invalid work-item.json: --help/work-item.json
|
||||
exit=1
|
||||
```
|
||||
|
||||
`exit 0` 이 usage 가 나왔다는 뜻은 아니다. `audit-records.py` 는 `--help` 라는 이름의
|
||||
프로젝트를 찾아 검사하고 통과시켰다.
|
||||
|
||||
## 손으로 적지 못하게 했다
|
||||
|
||||
관문 결과를 사람이 옮겨 적는 한 같은 뿌리에서 계속 난다. 그래서 명령을 돌리는 쪽과
|
||||
종료 코드를 적는 쪽을 하나로 붙였다.
|
||||
|
||||
```python
|
||||
proc = subprocess.run(command, cwd=cwd, capture_output=True,
|
||||
text=True, timeout=timeout)
|
||||
exit_code, out = proc.returncode, proc.stdout + proc.stderr
|
||||
```
|
||||
|
||||
셸 한 줄을 감싸는 래퍼도 됐지만 그러면 파이프를 다시 쓸 수 있게 된다. 값을 두 번 틀리게
|
||||
만든 것이 바로 그 셸이라 아예 거치지 않기로 했다. 대신 셸 문법이 필요한 명령은
|
||||
`bash -c` 를 인자로 넘겨야 하고, 그 안에서 다시 파이프를 쓰면 같은 실수가 난다 — 이 기록의
|
||||
증거 여섯 개도 그렇게 수집했다. 종료 코드를 인자로 받지 않으므로 손으로 적어 넣을 수는 없다. 원문은 `final/evidence/raw/` 에, 실행 메타는 `final/evidence/meta/` 에
|
||||
같은 이름으로 함께 떨어진다.
|
||||
|
||||
처음 판에서는 이 도구도 인자를 잘못 먹었다. `argparse.REMAINDER` 로 명령을 받았더니
|
||||
`--proves` 부터가 실행할 명령으로 딸려 가 `No such file or directory: '--proves'` 로 죽었다.
|
||||
지금은 `--` 앞뒤를 직접 가르고, 왜 그렇게 했는지를 코드에 한 줄로 남겨 두었다.
|
||||
|
||||
```python
|
||||
# `--` 앞뒤를 먼저 가른다. argparse.REMAINDER 에 맡기면 옵션이 명령으로 딸려 간다
|
||||
argv = sys.argv[1:]
|
||||
```
|
||||
|
||||
`--help` 를 위치 인자로 먹은 세 스크립트와 같은 종류의 실수다. 이 저장소에서 인자를 손으로
|
||||
가르는 코드는 대개 여기서 걸린다.
|
||||
|
||||
이 기록이 인용한 원문 다섯 개를 그 도구가 수집했다. 메타 하나는 이렇게 생겼다.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "help-exit-codes-measured-without-a-pipe",
|
||||
"kind": "terminal",
|
||||
"sourceRevision": "43e1aadef077ad93c30495df428ee3a71dd73f4a",
|
||||
"sourceDirty": true,
|
||||
"executedAt": "2026-09-10T09:54:41+09:00",
|
||||
"exitCode": 0,
|
||||
"exitCodeSource": "실행한 프로세스의 반환값. 손으로 적지 않는다",
|
||||
"rawPath": "evidence/raw/help-exit-codes-measured-without-a-pipe.txt",
|
||||
"proves": "파이프 없이 재면 같은 14개 중 build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다",
|
||||
"doesNotProve": "다른 인자에서의 동작. --help 하나만 잰 값이다",
|
||||
"sha256": "e8c134d07592bb1b051ea6ad3abf952a9fa502fc85eb26cdb56194447ea03a9b",
|
||||
"bytes": 410
|
||||
}
|
||||
```
|
||||
|
||||
여기서 `exitCode: 0` 은 **측정 반복문 자체가 끝까지 돌았다**고 말한다. 열넷 각각의 종료
|
||||
코드는 원문 `raw/` 안에 있다. 반복문이 반환한 값과 그 안에서 잰 값을 섞지 않는다 — 메타에는
|
||||
반복문 쪽이 들어간다.
|
||||
|
||||
`sourceDirty` 는 그 실행 시점에 작업 트리에 커밋 안 된 변경이 있었는지 적는다. 있으면
|
||||
`sourceRevision` 이 그 출력을 설명하지 못한다. 이 다섯은 전부 `true` 다 — 수집기 자신을
|
||||
더한 상태에서 쟀다.
|
||||
|
||||
기존 경로를 지우지 않았다. 손으로 만든 `raw/`·`meta/` 도 그대로 쓰이고, 이 도구는 필요할
|
||||
때만 부른다.
|
||||
|
||||
## 이 사건이 닫지 못한 것
|
||||
|
||||
수집기는 브라우저 캡처와 대화형 명령을 담지 못한다. 이 저장소의 증거 가운데
|
||||
`final/evidence/browser/` 쪽은 여전히 Playwright 로 찍고 메타를 손으로 적는다 — 종료 코드를
|
||||
손으로 적을 수 없게 만든 것이 아직 절반이라는 뜻이다.
|
||||
|
||||
<!-- body:end -->
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
id:
|
||||
kind: CASE
|
||||
slug: exit-code-read-behind-a-pipe
|
||||
title: 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
topic: pipeline-gate-exit-codes
|
||||
topicName: 관문의 종료 코드
|
||||
project: document-haness
|
||||
status: 게시 전
|
||||
studio: ""
|
||||
lastVerifiedOn: 2026-09-10
|
||||
source:
|
||||
- final/document.md#§2-관찰한-것
|
||||
- final/document.md#§3-파이프-뒤의-종료-코드
|
||||
- final/document.md#§4-다시-잰-값
|
||||
- final/document.md#§5-argparse-를-쓰지-않는-넷
|
||||
- final/document.md#§8-종료-코드를-손으로-적을-수-없게-만든다
|
||||
sourceRevision: 43e1aadef077ad93c30495df428ee3a71dd73f4a
|
||||
evidence:
|
||||
- ../../../final/evidence/raw/exit-code-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-without-a-pipe.txt
|
||||
- ../../../final/evidence/raw/argparse-absent-scripts.txt
|
||||
- ../../../final/evidence/raw/what-the-three-print-for-help.txt
|
||||
---
|
||||
|
||||
# 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
|
||||
scripts/ 의 검사기 열넷에 --help 를 돌려 전부 종료 코드 0 을 받았다. 이 저장소를 함께
|
||||
조사한 다른 세션도 같은 값을 얻어 확인 등급 확인함으로 적었다. 값은 검사기가 아니라 재는
|
||||
방법이 만든 것이었다. 파이프를 걷어 내고 다시 재니 둘이 exit 1 이다.
|
||||
|
||||
## 관계
|
||||
|
||||
- **검사할 것이 없을 때 관문은 무엇을 내야 하는가**
|
||||
이 사건에서 `audit-records.py --help` 가 「문제 없음」을 찍으면서 그 물음이 열렸다.
|
||||
`--help` 라는 이름의 프로젝트에는 검사할 기록이 하나도 없어 그대로 통과했다.
|
||||
|
||||
## 문제
|
||||
|
||||
관문은 종료 코드로 말한다. 단계 계약이 「관문은 종료 코드가 0 이어야 지난 것이다」 라고
|
||||
적었고, 런 원장 run.json 의 stages[].gates[].exit 에 그 값이 남는다. 사람이 셸에서 그 값을
|
||||
읽어 옮겨 적는다.
|
||||
|
||||
--help 하나를 잰 것뿐인데 값이 두 번 틀렸다. 관문 결과 전부가 같은 방법으로 적히고 있다.
|
||||
|
||||
## 결론
|
||||
|
||||
리비전 43e1aad 의 scripts/*.py 열넷 중 열둘이 --help 에 exit 0,
|
||||
build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다.
|
||||
exit 0 이 usage 가 나왔다는 뜻은 아니다 — audit-records.py 는 --help 를 프로젝트
|
||||
이름으로 받아 검사하고 통과시킨다.
|
||||
|
||||
값을 틀리게 만든 것은 셸의 동작 둘이다. 파이프의 종료 코드 변수는 마지막 명령을 가리키고,
|
||||
명령 치환은 그 변수를 덮어쓴다. 둘 다 정의된 동작이라 셸이 경고하지 않는다.
|
||||
|
||||
조치로 scripts/capture-evidence.py 를 만들었다. 명령을 subprocess 로 직접 돌리고 그
|
||||
프로세스의 반환값을 그대로 메타에 적는다. 종료 코드를 인자로 받지 않으므로 손으로 적을
|
||||
경로가 없다.
|
||||
|
||||
## 검증 환경
|
||||
|
||||
python 3.12.3 · node v24.14.0 · bash 5.2.21(1)-release · Linux.
|
||||
대상 저장소 document-haness 리비전 43e1aadef077ad93c30495df428ee3a71dd73f4a.
|
||||
측정은 그 커밋에서 갈라진 worktree dh-B 에서 했고, 그 시점 작업 트리에는
|
||||
capture-evidence.py 가 더해져 있어 증거 메타의 sourceDirty 가 true 다.
|
||||
측정 대상 열넷은 git ls-tree 로 그 커밋의 목록만 골라 냈다.
|
||||
|
||||
## 재현 조건
|
||||
|
||||
1. document-haness 를 43e1aad 로 체크아웃한다.
|
||||
2. 파이프를 끼고 잰다 — 반복문 안에서 python3 출력을 head 로 넘기고 그다음 줄에서 $? 를 읽는다.
|
||||
3. 열넷이 전부 exit=0 으로 나오는 것을 본다.
|
||||
4. 파이프를 걷고 out=$(...) 다음 줄에서 code=$? 로 받아 다시 잰다.
|
||||
5. build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit=1 로 갈리는 것을 본다.
|
||||
|
||||
## 본문
|
||||
|
||||
<!-- body:start -->
|
||||
|
||||
## 두 번 같은 값이 나왔다
|
||||
|
||||
검사기 목록을 만들려고 열넷에 `--help` 를 돌렸다. 출력이 길어서 `head` 로 잘랐다.
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
timeout 60 python3 $s --help 2>&1 | head -30 >/dev/null
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
열넷이 전부 `exit=0` 이었다.
|
||||
|
||||
```
|
||||
audit-records.py exit=0
|
||||
build-tech-log-tree.py exit=0
|
||||
check-figure-overlap.py exit=0
|
||||
check-figure-text.py exit=0
|
||||
fold-analysis-into-final.py exit=0
|
||||
fold-studio-contract-into-index.py exit=0
|
||||
preview-figure.py exit=0
|
||||
studio-body.py exit=0
|
||||
techlog.py exit=0
|
||||
verify-pipeline-run.py exit=0
|
||||
verify-pipeline.py exit=0
|
||||
verify-project-layout.py exit=0
|
||||
verify-refactor-work-item.py exit=0
|
||||
verify-tech-log-tree.py exit=0
|
||||
```
|
||||
|
||||
이 저장소를 함께 조사한 다른 세션도 같은 값을 얻어 「`scripts/*.py` 14개 전부 `--help` 가
|
||||
종료 코드 0 으로 돌아온다」 를 확인 등급 **확인함**으로 적었다. 두 사람이 같은 값을 얻었으니
|
||||
맞는 값처럼 보였다.
|
||||
|
||||
## 값을 만든 것은 셸이다
|
||||
|
||||
파이프라인의 `$?` 는 **마지막** 명령의 종료 코드다. `head` 는 언제나 성공하므로 앞의
|
||||
`python3` 가 무엇을 반환하든 `$?` 는 0 이 된다.
|
||||
|
||||
```bash
|
||||
set +o pipefail
|
||||
false | head -1; echo "false | head -1 -> exit=$?"
|
||||
false; echo "false -> exit=$?"
|
||||
```
|
||||
|
||||
```
|
||||
false | head -1 -> exit=0
|
||||
false -> exit=1
|
||||
bash 5.2.21(1)-release
|
||||
```
|
||||
|
||||
POSIX 셸의 정의된 동작이고 이 셸의 특이점이 아니다. `pipefail` 을 켜거나
|
||||
`${PIPESTATUS[0]}` 를 읽으면 앞 명령의 값을 얻는다.
|
||||
|
||||
같은 착각이 한 번 더 났다. 파이프를 걷어 내고 다시 잴 때 이렇게 썼다.
|
||||
|
||||
```bash
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
echo "$(basename $s) exit=$?"
|
||||
```
|
||||
|
||||
명령 치환 `$(basename $s)` 가 먼저 실행되면서 `$?` 를 덮어썼다. 그래서 두 번째 측정도
|
||||
열넷 전부 0 이었다. `code=$?` 를 명령 바로 다음 줄에 두고서야 값이 갈렸다.
|
||||
|
||||
## 다시 잰 값
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
두 측정의 차이는 두 줄뿐이다. 잰 것은 `--help` 하나뿐이라 나머지 열둘이 다른 인자에서
|
||||
어떻게 도는지는 이 값이 말해 주지 않는다.
|
||||
|
||||
```
|
||||
2c2
|
||||
< build-tech-log-tree.py exit=0
|
||||
---
|
||||
> build-tech-log-tree.py exit=1
|
||||
13c13
|
||||
< verify-refactor-work-item.py exit=0
|
||||
---
|
||||
> verify-refactor-work-item.py exit=1
|
||||
```
|
||||
|
||||
## 왜 그 둘만인가
|
||||
|
||||
열넷 중 넷이 `argparse` 를 쓰지 않는다.
|
||||
|
||||
| 스크립트 | `argparse` | `--help` |
|
||||
|---|---|---|
|
||||
| `audit-records.py` | 없음 | `exit 0` — 「문제 없음」 |
|
||||
| `build-tech-log-tree.py` | 없음 | `exit 1` |
|
||||
| `techlog.py` | 없음 | `exit 0` — CLI 가 아니라 인자를 안 읽는다 |
|
||||
| `verify-refactor-work-item.py` | 없음 | `exit 1` |
|
||||
| 나머지 열 | 있음 | `exit 0` — usage |
|
||||
|
||||
남은 셋은 `--help` 를 옵션이 아니라 위치 인자로 먹는다. `audit-records.py` 는 그것을
|
||||
프로젝트 이름으로 받아 「문제 없음」을 찍고, `build-tech-log-tree.py` 와
|
||||
`verify-refactor-work-item.py` 는 그 이름의 파일을 못 찾아 실패한다.
|
||||
|
||||
```
|
||||
$ python3 scripts/audit-records.py --help
|
||||
|
||||
--help — 기록 0건 · 원문 0 · 메타 0 · 렌더 0
|
||||
문제 없음
|
||||
|
||||
합계 0건
|
||||
exit=0
|
||||
|
||||
$ python3 scripts/build-tech-log-tree.py --help
|
||||
--help: tech-log-tree.json 이 없다. 글감을 먼저 적는다
|
||||
exit=1
|
||||
|
||||
$ python3 scripts/verify-refactor-work-item.py --help
|
||||
REFACTOR WORK ITEM VERIFICATION: FAIL
|
||||
- invalid work-item.json: --help/work-item.json
|
||||
exit=1
|
||||
```
|
||||
|
||||
`exit 0` 이 usage 가 나왔다는 뜻은 아니다. `audit-records.py` 는 `--help` 라는 이름의
|
||||
프로젝트를 찾아 검사하고 통과시켰다.
|
||||
|
||||
## 손으로 적지 못하게 했다
|
||||
|
||||
관문 결과를 사람이 옮겨 적는 한 같은 뿌리에서 계속 난다. 그래서 명령을 돌리는 쪽과
|
||||
종료 코드를 적는 쪽을 하나로 붙였다.
|
||||
|
||||
```python
|
||||
proc = subprocess.run(command, cwd=cwd, capture_output=True,
|
||||
text=True, timeout=timeout)
|
||||
exit_code, out = proc.returncode, proc.stdout + proc.stderr
|
||||
```
|
||||
|
||||
셸 한 줄을 감싸는 래퍼도 됐지만 그러면 파이프를 다시 쓸 수 있게 된다. 값을 두 번 틀리게
|
||||
만든 것이 바로 그 셸이라 아예 거치지 않기로 했다. 대신 셸 문법이 필요한 명령은
|
||||
`bash -c` 를 인자로 넘겨야 하고, 그 안에서 다시 파이프를 쓰면 같은 실수가 난다 — 이 기록의
|
||||
증거 여섯 개도 그렇게 수집했다. 종료 코드를 인자로 받지 않으므로 손으로 적어 넣을 수는 없다. 원문은 `final/evidence/raw/` 에, 실행 메타는 `final/evidence/meta/` 에
|
||||
같은 이름으로 함께 떨어진다.
|
||||
|
||||
처음 판에서는 이 도구도 인자를 잘못 먹었다. `argparse.REMAINDER` 로 명령을 받았더니
|
||||
`--proves` 부터가 실행할 명령으로 딸려 가 `No such file or directory: '--proves'` 로 죽었다.
|
||||
지금은 `--` 앞뒤를 직접 가르고, 왜 그렇게 했는지를 코드에 한 줄로 남겨 두었다.
|
||||
|
||||
```python
|
||||
# `--` 앞뒤를 먼저 가른다. argparse.REMAINDER 에 맡기면 옵션이 명령으로 딸려 간다
|
||||
argv = sys.argv[1:]
|
||||
```
|
||||
|
||||
`--help` 를 위치 인자로 먹은 세 스크립트와 같은 종류의 실수다. 이 저장소에서 인자를 손으로
|
||||
가르는 코드는 대개 여기서 걸린다.
|
||||
|
||||
이 기록이 인용한 원문 다섯 개를 그 도구가 수집했다. 메타 하나는 이렇게 생겼다.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "help-exit-codes-measured-without-a-pipe",
|
||||
"kind": "terminal",
|
||||
"sourceRevision": "43e1aadef077ad93c30495df428ee3a71dd73f4a",
|
||||
"sourceDirty": true,
|
||||
"executedAt": "2026-09-10T09:54:41+09:00",
|
||||
"exitCode": 0,
|
||||
"exitCodeSource": "실행한 프로세스의 반환값. 손으로 적지 않는다",
|
||||
"rawPath": "evidence/raw/help-exit-codes-measured-without-a-pipe.txt",
|
||||
"proves": "파이프 없이 재면 같은 14개 중 build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다",
|
||||
"doesNotProve": "다른 인자에서의 동작. --help 하나만 잰 값이다",
|
||||
"sha256": "e8c134d07592bb1b051ea6ad3abf952a9fa502fc85eb26cdb56194447ea03a9b",
|
||||
"bytes": 410
|
||||
}
|
||||
```
|
||||
|
||||
여기서 `exitCode: 0` 은 **측정 반복문 자체가 끝까지 돌았다**고 말한다. 열넷 각각의 종료
|
||||
코드는 원문 `raw/` 안에 있다. 반복문이 반환한 값과 그 안에서 잰 값을 섞지 않는다 — 메타에는
|
||||
반복문 쪽이 들어간다.
|
||||
|
||||
`sourceDirty` 는 그 실행 시점에 작업 트리에 커밋 안 된 변경이 있었는지 적는다. 있으면
|
||||
`sourceRevision` 이 그 출력을 설명하지 못한다. 이 다섯은 전부 `true` 다 — 수집기 자신을
|
||||
더한 상태에서 쟀다.
|
||||
|
||||
기존 경로를 지우지 않았다. 손으로 만든 `raw/`·`meta/` 도 그대로 쓰이고, 이 도구는 필요할
|
||||
때만 부른다.
|
||||
|
||||
## 이 사건이 닫지 못한 것
|
||||
|
||||
수집기는 브라우저 캡처와 대화형 명령을 담지 못한다. 이 저장소의 증거 가운데
|
||||
`final/evidence/browser/` 쪽은 여전히 Playwright 로 찍고 메타를 손으로 적는다 — 종료 코드를
|
||||
손으로 적을 수 없게 만든 것이 아직 절반이라는 뜻이다.
|
||||
|
||||
<!-- body:end -->
|
||||
@@ -0,0 +1,278 @@
|
||||
---
|
||||
id:
|
||||
kind: CASE
|
||||
slug: exit-code-read-behind-a-pipe
|
||||
title: 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
topic: pipeline-gate-exit-codes
|
||||
topicName: 관문의 종료 코드
|
||||
project: document-haness
|
||||
status: 게시 전
|
||||
studio: ""
|
||||
lastVerifiedOn: 2026-09-10
|
||||
source:
|
||||
- final/document.md#§2-관찰한-것
|
||||
- final/document.md#§3-파이프-뒤의-종료-코드
|
||||
- final/document.md#§4-다시-잰-값
|
||||
- final/document.md#§5-argparse-를-쓰지-않는-넷
|
||||
- final/document.md#§8-종료-코드를-손으로-적을-수-없게-만든다
|
||||
sourceRevision: 43e1aadef077ad93c30495df428ee3a71dd73f4a
|
||||
evidence:
|
||||
- ../../../final/evidence/raw/exit-code-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-through-a-pipe.txt
|
||||
- ../../../final/evidence/raw/help-exit-codes-measured-without-a-pipe.txt
|
||||
- ../../../final/evidence/raw/argparse-absent-scripts.txt
|
||||
- ../../../final/evidence/raw/what-the-three-print-for-help.txt
|
||||
---
|
||||
|
||||
# 파이프 뒤의 종료 코드를 읽고 검사기 열넷이 다 통과한다고 적었다
|
||||
|
||||
scripts/ 의 검사기 열넷에 --help 를 돌려 전부 종료 코드 0 을 받았고, 이 저장소를 함께
|
||||
조사한 다른 세션도 같은 값을 얻어 확인 등급 확인함으로 적었다. 값은 검사기가 아니라 재는
|
||||
방법이 만든 것이었다. 파이프를 걷어 내고 다시 재니 둘이 exit 1 이다.
|
||||
|
||||
## 관계
|
||||
|
||||
- **검사할 것이 없을 때 관문은 무엇을 내야 하는가**
|
||||
이 사건에서 `audit-records.py --help` 가 「문제 없음」을 찍으면서 그 물음이 열렸다.
|
||||
`--help` 라는 이름의 프로젝트에는 검사할 기록이 하나도 없어 그대로 통과했다.
|
||||
|
||||
## 문제
|
||||
|
||||
관문은 종료 코드로 말한다. 단계 계약이 「관문은 종료 코드가 0 이어야 지난 것이다」 라고
|
||||
적었고, 런 원장 run.json 의 stages[].gates[].exit 에 그 값이 남는데, 그 값을 사람이 셸에서
|
||||
읽어 옮겨 적는다.
|
||||
|
||||
--help 하나를 잰 것뿐인데 값이 두 번 틀렸다. 관문 결과 전부가 같은 방법으로 적히고 있다.
|
||||
|
||||
## 결론
|
||||
|
||||
리비전 43e1aad 의 scripts/*.py 열넷 중 열둘이 --help 에 exit 0,
|
||||
build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다.
|
||||
exit 0 이 usage 가 나왔다는 뜻은 아니다 — audit-records.py 는 --help 를 프로젝트
|
||||
이름으로 받아 검사하고 통과시킨다.
|
||||
|
||||
값을 틀리게 만든 것은 셸의 동작 둘이다. 파이프의 종료 코드 변수는 마지막 명령을 가리키고,
|
||||
명령 치환은 그 변수를 덮어쓴다. 둘 다 정의된 동작이라 셸이 경고하지 않는다.
|
||||
|
||||
조치로 만든 scripts/capture-evidence.py 는 명령을 subprocess 로 직접 돌리고 그 프로세스의
|
||||
반환값을 그대로 메타에 적는다. 종료 코드를 인자로 받지 않으므로 손으로 적을 경로가 없다.
|
||||
|
||||
## 검증 환경
|
||||
|
||||
python 3.12.3 · node v24.14.0 · bash 5.2.21(1)-release · Linux.
|
||||
대상 저장소 document-haness 리비전 43e1aadef077ad93c30495df428ee3a71dd73f4a.
|
||||
측정은 그 커밋에서 갈라진 worktree dh-B 에서 했고, 그 시점 작업 트리에는
|
||||
capture-evidence.py 가 더해져 있어 증거 메타의 sourceDirty 가 true 다.
|
||||
측정 대상 열넷은 git ls-tree 로 그 커밋의 목록만 골라 냈다.
|
||||
|
||||
## 재현 조건
|
||||
|
||||
1. document-haness 를 43e1aad 로 체크아웃한다.
|
||||
2. 파이프를 끼고 잰다 — 반복문 안에서 python3 출력을 head 로 넘기고 그다음 줄에서 $? 를 읽는다.
|
||||
3. 열넷이 전부 exit=0 으로 나오는 것을 본다.
|
||||
4. 파이프를 걷고 out=$(...) 다음 줄에서 code=$? 로 받아 다시 잰다.
|
||||
5. build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit=1 로 갈리는 것을 본다.
|
||||
|
||||
## 본문
|
||||
|
||||
<!-- body:start -->
|
||||
|
||||
## 두 번 같은 값이 나왔다
|
||||
|
||||
검사기 목록을 만들려고 열넷에 `--help` 를 돌렸는데, 출력이 길어서 `head` 로 잘랐다.
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
timeout 60 python3 $s --help 2>&1 | head -30 >/dev/null
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
열넷이 전부 `exit=0` 이었다.
|
||||
|
||||
```
|
||||
audit-records.py exit=0
|
||||
build-tech-log-tree.py exit=0
|
||||
check-figure-overlap.py exit=0
|
||||
check-figure-text.py exit=0
|
||||
fold-analysis-into-final.py exit=0
|
||||
fold-studio-contract-into-index.py exit=0
|
||||
preview-figure.py exit=0
|
||||
studio-body.py exit=0
|
||||
techlog.py exit=0
|
||||
verify-pipeline-run.py exit=0
|
||||
verify-pipeline.py exit=0
|
||||
verify-project-layout.py exit=0
|
||||
verify-refactor-work-item.py exit=0
|
||||
verify-tech-log-tree.py exit=0
|
||||
```
|
||||
|
||||
이 저장소를 함께 조사한 다른 세션도 같은 값을 얻어 「`scripts/*.py` 14개 전부 `--help` 가
|
||||
종료 코드 0 으로 돌아온다」 를 확인 등급 **확인함**으로 적었다. 두 사람이 같은 값을 얻었으니
|
||||
맞는 값처럼 보였다.
|
||||
|
||||
## 값을 만든 것은 셸이다
|
||||
|
||||
파이프라인의 `$?` 는 **마지막** 명령의 종료 코드다. `head` 는 언제나 성공하므로 앞의
|
||||
`python3` 가 무엇을 반환하든 `$?` 는 0 이 된다.
|
||||
|
||||
```bash
|
||||
set +o pipefail
|
||||
false | head -1; echo "false | head -1 -> exit=$?"
|
||||
false; echo "false -> exit=$?"
|
||||
```
|
||||
|
||||
```
|
||||
false | head -1 -> exit=0
|
||||
false -> exit=1
|
||||
bash 5.2.21(1)-release
|
||||
```
|
||||
|
||||
POSIX 셸의 정의된 동작이고 이 셸의 특이점이 아니다. `pipefail` 을 켜거나
|
||||
`${PIPESTATUS[0]}` 를 읽으면 앞 명령의 값을 얻는다.
|
||||
|
||||
같은 착각이 한 번 더 났다. 파이프를 걷어 내고 다시 잴 때 이렇게 썼다.
|
||||
|
||||
```bash
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
echo "$(basename $s) exit=$?"
|
||||
```
|
||||
|
||||
명령 치환 `$(basename $s)` 가 먼저 실행되면서 `$?` 를 덮어써서 두 번째 측정도 열넷 전부
|
||||
0 이었다. `code=$?` 를 명령 바로 다음 줄에 두고서야 값이 갈렸다.
|
||||
|
||||
## 다시 잰 값
|
||||
|
||||
```bash
|
||||
for s in $(git ls-tree --name-only 43e1aad scripts/ | grep '\.py$'); do
|
||||
out=$(timeout 60 python3 $s --help 2>&1)
|
||||
code=$?
|
||||
n=$(basename $s)
|
||||
echo "$n exit=$code"
|
||||
done
|
||||
```
|
||||
|
||||
두 측정의 차이는 두 줄뿐이다.
|
||||
|
||||
```
|
||||
2c2
|
||||
< build-tech-log-tree.py exit=0
|
||||
---
|
||||
> build-tech-log-tree.py exit=1
|
||||
13c13
|
||||
< verify-refactor-work-item.py exit=0
|
||||
---
|
||||
> verify-refactor-work-item.py exit=1
|
||||
```
|
||||
|
||||
잰 것은 `--help` 하나뿐이라 나머지 열둘이 다른 인자에서 어떻게 도는지는 이 값이 말해 주지
|
||||
않는다.
|
||||
|
||||
## 왜 그 둘만인가
|
||||
|
||||
열넷 중 넷이 `argparse` 를 쓰지 않는다.
|
||||
|
||||
| 스크립트 | `argparse` | `--help` |
|
||||
|---|---|---|
|
||||
| `audit-records.py` | 없음 | `exit 0` — 「문제 없음」 |
|
||||
| `build-tech-log-tree.py` | 없음 | `exit 1` |
|
||||
| `techlog.py` | 없음 | `exit 0` — CLI 가 아니라 인자를 안 읽는다 |
|
||||
| `verify-refactor-work-item.py` | 없음 | `exit 1` |
|
||||
| 나머지 열 | 있음 | `exit 0` — usage |
|
||||
|
||||
남은 셋은 `--help` 를 옵션이 아니라 위치 인자로 먹는다. `audit-records.py` 는 그것을
|
||||
프로젝트 이름으로 받아 「문제 없음」을 찍고, `build-tech-log-tree.py` 와
|
||||
`verify-refactor-work-item.py` 는 그 이름의 파일을 못 찾아 실패한다.
|
||||
|
||||
```
|
||||
$ python3 scripts/audit-records.py --help
|
||||
|
||||
--help — 기록 0건 · 원문 0 · 메타 0 · 렌더 0
|
||||
문제 없음
|
||||
|
||||
합계 0건
|
||||
exit=0
|
||||
|
||||
$ python3 scripts/build-tech-log-tree.py --help
|
||||
--help: tech-log-tree.json 이 없다. 글감을 먼저 적는다
|
||||
exit=1
|
||||
|
||||
$ python3 scripts/verify-refactor-work-item.py --help
|
||||
REFACTOR WORK ITEM VERIFICATION: FAIL
|
||||
- invalid work-item.json: --help/work-item.json
|
||||
exit=1
|
||||
```
|
||||
|
||||
`exit 0` 이 usage 가 나왔다는 뜻은 아니다. `audit-records.py` 는 `--help` 라는 이름의
|
||||
프로젝트를 찾아 검사하고 통과시켰다.
|
||||
|
||||
## 손으로 적지 못하게 했다
|
||||
|
||||
관문 결과를 사람이 옮겨 적는 한 같은 뿌리에서 같은 실수가 계속 난다. 그래서 명령을 돌리는
|
||||
쪽과 종료 코드를 적는 쪽을 하나로 붙였다.
|
||||
|
||||
```python
|
||||
proc = subprocess.run(command, cwd=cwd, capture_output=True,
|
||||
text=True, timeout=timeout)
|
||||
exit_code, out = proc.returncode, proc.stdout + proc.stderr
|
||||
```
|
||||
|
||||
종료 코드를 인자로 받지 않으므로 손으로 적어 넣을 수는 없다. 원문은
|
||||
`final/evidence/raw/` 에, 실행 메타는 `final/evidence/meta/` 에 같은 이름으로 함께 떨어진다.
|
||||
|
||||
셸 한 줄을 감싸는 래퍼도 됐지만 그러면 파이프를 다시 쓸 수 있게 된다. 값을 두 번 틀리게
|
||||
만든 것이 바로 그 셸이라 아예 거치지 않기로 했다. 대신 셸 문법이 필요한 명령은 `bash -c` 를
|
||||
인자로 넘겨야 하고, 그 안에서 다시 파이프를 쓰면 같은 실수가 난다 — 이 기록의 증거
|
||||
다섯 개도 그렇게 수집했다.
|
||||
|
||||
처음 판에서는 이 도구도 인자를 잘못 먹었다. `argparse.REMAINDER` 로 명령을 받았더니
|
||||
`--proves` 부터가 실행할 명령으로 딸려 가 `No such file or directory: '--proves'` 로 죽었다.
|
||||
지금은 `--` 앞뒤를 직접 가르고, 왜 그렇게 했는지를 코드에 한 줄로 남겨 두었다.
|
||||
|
||||
```python
|
||||
# `--` 앞뒤를 먼저 가른다. argparse.REMAINDER 에 맡기면 옵션이 명령으로 딸려 간다
|
||||
argv = sys.argv[1:]
|
||||
```
|
||||
|
||||
`--help` 를 위치 인자로 먹은 세 스크립트와 같은 종류의 실수다. 이 저장소에서 인자를 손으로
|
||||
가르는 코드는 대개 여기서 걸린다.
|
||||
|
||||
이 기록이 인용한 원문 다섯 개를 그 도구가 수집했다. 메타 하나는 이렇게 생겼다.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "help-exit-codes-measured-without-a-pipe",
|
||||
"kind": "terminal",
|
||||
"sourceRevision": "43e1aadef077ad93c30495df428ee3a71dd73f4a",
|
||||
"sourceDirty": true,
|
||||
"executedAt": "2026-09-10T09:54:41+09:00",
|
||||
"exitCode": 0,
|
||||
"exitCodeSource": "실행한 프로세스의 반환값. 손으로 적지 않는다",
|
||||
"rawPath": "evidence/raw/help-exit-codes-measured-without-a-pipe.txt",
|
||||
"proves": "파이프 없이 재면 같은 14개 중 build-tech-log-tree.py 와 verify-refactor-work-item.py 가 exit 1 이다",
|
||||
"doesNotProve": "다른 인자에서의 동작. --help 하나만 잰 값이다",
|
||||
"sha256": "e8c134d07592bb1b051ea6ad3abf952a9fa502fc85eb26cdb56194447ea03a9b",
|
||||
"bytes": 410
|
||||
}
|
||||
```
|
||||
|
||||
여기서 `exitCode: 0` 은 **측정 반복문 자체가 끝까지 돌았다**고 말한다. 열넷 각각의 종료
|
||||
코드는 원문 `raw/` 안에 있다. 반복문이 반환한 값과 그 안에서 잰 값을 섞지 않는다 — 메타에는
|
||||
반복문 쪽이 들어간다.
|
||||
|
||||
`sourceDirty` 는 그 실행 시점에 작업 트리에 커밋 안 된 변경이 있었는지 적는다. 있으면
|
||||
`sourceRevision` 이 그 출력을 설명하지 못한다. 이 다섯은 전부 `true` 다 — 수집기 자신을
|
||||
더한 상태에서 쟀다.
|
||||
|
||||
기존 경로를 지우지 않았다. 손으로 만든 `raw/`·`meta/` 도 그대로 쓰이고, 이 도구는 필요할
|
||||
때만 부른다.
|
||||
|
||||
## 이 사건이 닫지 못한 것
|
||||
|
||||
수집기는 브라우저 캡처와 대화형 명령을 담지 못한다. 이 저장소의 증거 가운데
|
||||
`final/evidence/browser/` 쪽은 여전히 Playwright 로 찍고 메타를 손으로 적는다 — 종료 코드를
|
||||
손으로 적을 수 없게 만든 것이 아직 절반이라는 뜻이다.
|
||||
|
||||
<!-- body:end -->
|
||||
Reference in New Issue
Block a user