makdoong2-team 1.7.0 → 1.8.0

package/README.md

@@ -106,6 +106,7 @@ makdoong2-team doctor            # 설치 진단
 - 커맨드가 **전용 full-permission 에이전트**(`makdoong2-issue-reporter`)로 라우팅되어, 호출 시점 이전의 로그·프롬프트·세션 컨텍스트를 스스로 수집해 이상 지점을 포착하고 [y00njinuk/makdoong2-team issues](https://github.com/y00njinuk/makdoong2-team/issues) 에 등록한다.
 - **사용자 직접 호출이 유일한 트리거**다. 부장님·막둥이가 실패를 관측했다고 자율적으로 이슈를 만들지 않는다 (훅이 차단). 이 에이전트는 **선택 가능한 에이전트 목록에도, `@` 멘션 목록에도 뜨지 않으며**, `task` 툴로 spawn 하는 것도 차단된다 — 진입점은 위 커맨드 하나뿐이다.
 - 저장소가 public 이므로 사내 정보는 마스킹 후 첨부되며, **전송 전 승인을 세션 안에서 묻는다**: 에이전트가 게시될 원문 전체를 `cat` 으로 표시하면 훅이 그 sha256 을 기록하고, 전송용 curl 호출 시 opencode 가 게시 여부를 묻는다(yes/no). 표시하지 않았거나 표시 후 내용이 바뀌면 전송이 차단된다 (승인은 사용자가 본 원문에 바인딩, 1회용). 승인 프롬프트에서는 **"Allow once"** 를 고른다 — "always" 는 남은 세션의 승인 질문을 없앤다.
+- **이슈 본문은 고정 양식으로 쓴다.** 증상 · 환경 · 재현 절차 · 기대/실제 동작 · 실패 지점 · 타임라인 · 에러 메시지 · 재현성/영향 범위 · 시도한 조치 · 증거(필수)에, 조사에서 근거가 나오면 관련 관찰 · 의심 근본 원인 코드 · 부수 관찰 · 제안(조건부)이 붙는다. 양식은 발명이 아니라 [#5](https://github.com/y00njinuk/makdoong2-team/issues/5) 가 실제로 갖췄던 구성을 규약화한 것이다 — 그 이슈의 증거가 그대로 진단에 쓰여 v1.7.0 수정으로 이어졌다. 상세: `skills/makdoong2-issue-reporter/SKILL.md` §6
 - PAT 는 `~/.config/opencode/.github` 파일에서 읽는다. **파일이 없거나 토큰을 찾지 못하면 중단하지 않고, 발급 URL 과 최소 권한(fine-grained: Issues Read/write, classic: `public_repo`)을 안내해 사용자에게 발급을 요청한 뒤 대기**한다. 401/403 도 같은 재발급 경로를 탄다. 상세: ARCHITECTURE.md §4.6
 
 ---

package/agents/makdoong2-issue-reporter.md

@@ -39,7 +39,7 @@ permission:
 
 ## 하드룰
 
-1. **첫 행동으로 `skill(name="makdoong2-issue-reporter")` 를 로드**하고, 스킬에 정의된 절차를 그대로 따른다. 실행 순서는 스킬이 고정한다: **수집 → 이상 지점 포착 → 마스킹 → 중복 확인 → 최소 질의 → 이슈 생성**.
+1. **첫 행동으로 `skill(name="makdoong2-issue-reporter")` 를 로드**하고, 스킬에 정의된 절차를 그대로 따른다. 실행 순서는 스킬이 고정한다: **수집 → 이상 지점 포착 → 마스킹 → 중복 확인 → 최소 질의 → 본문 작성 → 이슈 생성**.
 2. **GitHub 게시(이슈·코멘트·Gist·라벨)는 훅이 강제하는 사용자 승인 게이트를 통과해야만 가능하다.** 절차는 고정이다:
    1. payload 를 **리터럴 절대 경로** JSON 파일로 작성한다 (예: `/tmp/makdoong2-issue/issue-payload.json`).
    2. **게시될 원문 전체를 `cat <payload>` 로 세션에 표시**하고 마스킹 내역 요약을 덧붙인다. 이 `cat` 은 **체이닝 없이 단독 실행**해야 하며(`;`·`&&`·리다이렉트·`$()` 금지), 훅이 이 시점의 sha256 을 표시 증명으로 기록한다. 요약·발췌로 대체 금지 — 사용자는 전송될 원문을 봐야 한다.
@@ -50,6 +50,7 @@ permission:
 3. **토큰(PAT)은 어디에도 원문 노출 금지.** 커맨드 문자열에 직접 박지 않고 환경변수로 전달하며, 출력에는 마스킹(`ghp_****`)만 허용한다.
 4. **워크플로우 상태를 변경하지 않는다.** state.json 은 증거 수집을 위한 읽기(`state.sh get`)만 허용. `state.sh set` / dispatch 계열 툴 호출 금지. 이 에이전트는 워크플로우 오케스트레이션과 완전히 분리된 조사·보고 전용이다.
 5. **다른 에이전트로 위임하지 않는다.** 수집·분석·마스킹·등록 전 과정을 이 세션에서 직접 수행한다.
+6. **이슈 본문은 스킬 6장 양식을 따른다.** 필수 섹션 10개와 `## 증거` 를 순서대로 채우고, 3장 수집에서 근거가 나온 조건부 섹션(`## 관련 관찰` / `## 참고: 의심 근본 원인 코드` / `## 부수 관찰 (minor)` / `## 제안 (참고)`)을 빠뜨리지 않는다. 모든 인용에 출처(파일+라인 또는 세션+턴)를 달고 단정과 추정을 구분한다(추정은 `> 추정:`). **payload 를 `cat` 으로 표시하기 전에 6.6 자기 점검을 통과시킨다** — 표시 후 본문을 고치면 표시 증명이 무효가 되어 하드룰 2 를 2번부터 다시 밟아야 한다. 기준 사례는 이슈 #5 다.
 
 ## 실행 컨텍스트
 

package/agents/makdoong2-verifier.md

@@ -94,10 +94,10 @@ bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."2_implementation".substage
 `<STAGES_DIR>/NN-*.md`을 읽어 단계가 요구한 *명시적 산출물*을 추출한다.
 - 1_planning.jira: **통합 planning spec(01-planning.md)** 사용 — 3개 substage를 한 번에 처리하므로 다음 모두 확인:
     - `jira`: `template_validation` 6항목 모두 기록 + `validation_passed=true` + `done=true`
-    - `requirements`: `done=true` + `policy.category`(minor|major) 설정 + `self_check.categorized==true` + `requirements-draft.md` 존재
+    - `requirements`: `done=true` + `policy.category`(minor|major) 설정 + `self_check.categorized==true` + **`draft_path` 마커 기록 + 그 경로의 파일 존재** (아래 §2-4 참조)
     - `scope`: `done=true` + `self_check.paths_explicit=true`
     - **interview_required=true가 기록되어 있고 requirements.done=false이면**: 인터뷰 대기 상태 → **REJECTED** (부장님이 인터뷰 후 재dispatch 필요)
-- 1_planning.requirements: (단독 dispatch 폴백 시) `done_at` / `verification_pending` / `requirements-draft.md` 존재 + `.policy.category` 설정 + `self_check.categorized==true`
+- 1_planning.requirements: (단독 dispatch 폴백 시) `done_at` / `verification_pending` + **`draft_path` 마커 기록 + 그 경로의 파일 존재** (아래 §2-4) + `.policy.category` 설정 + `self_check.categorized==true`
 - 1_planning.scope: (단독 dispatch 폴백 시) 4가지 출력 형식 항목 + `done=true`
 - 2_implementation.analysis:
     - `.skipped == true` 이면 즉시 **VERIFIED** (게이트가 SKIP 처리한 경우이므로 산출물 없음)
@@ -114,7 +114,11 @@ bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."2_implementation".substage
         - `integration_points` 배열 길이 >= 1
         - `test_conventions.framework` 가 존재하고 비어있지 않음 (`null`/빈 문자열 불가 — `"none"` 은 허용)
         - `.self_check` 의 **7개** boolean (`has_project_structure` / `has_dependencies` / `has_task_relevant_files` / `has_conventions` / `has_integration_points` / `has_test_conventions` / `json_schema_valid`) 모두 true
-        - `git status --porcelain` 이 `workspace-analysis.json` 외 다른 파일 변경/신규를 보고하지 않음 (analyzer 위반 신호)
+        - `git status --porcelain` 이 **플러그인 자신의 상태 디렉터리(`.makdoong2-team/`)를 뺀 뒤** `workspace-analysis.json` 외 다른 파일 변경/신규를 보고하지 않음 (analyzer 위반 신호)
+          ```bash
+          git status --porcelain | grep -v '\.makdoong2-team/' | grep -v 'workspace-analysis\.json'
+          ```
+          출력이 비어 있어야 한다. `.makdoong2-team/` 은 플러그인이 작업 트리 안에 만드는 **자기 상태**이지 analyzer 의 부산물이 아니다. 이것을 위반으로 세면 해당 패턴이 git exclude 에 없는 저장소에서 **항상 REJECTED** 가 나고, 그 시점에 exclude 를 고칠 권한을 가진 역할이 파이프라인에 없어(analyzer 는 산출물 1개만 쓰기 가능 · team-leader 는 하드룰 2 로 차단 · engineer 는 analysis 통과 후 단계) 동일 사유 무한 루프가 된다 (issue #6-②).
 - 2_implementation.dev: `done=true` + sub-agent output에 "테스트 추가" 명시 / 5체크
 - 2_implementation.test: `.stages."2_implementation".substages."test"` 의 각 필드가 아래 조건을 모두 충족해야 함
         - `.unit` ∈ `{"pass", "fail", "skip"}` — `none`/`null` 은 미기록 → REJECTED
@@ -271,10 +275,28 @@ BB_BASE=$(jq -r '.hosts.BITBUCKET_API_BASE_PATH' ~/.config/opencode/makdoong2-te
 
 5. 위 4단계 모두 통과 시 § 2-2 (앵커 재검증) 로 계속.
 
+### 2-4. 1_planning.requirements 전용: draft_path 마커 재검증
+
+게이트(`stage3-scope-verify.sh`)는 `spec_hash` 가 기록돼 있으면 `draft_path` **마커**를 하드 요구한다. 반면 종전 verifier 기준은 `requirements-draft.md` **파일 존재**만 봤다. 두 기준이 어긋나 있어서, `spec_hash` 는 기록하고 `draft_path` 는 빠뜨린 채 `done=true` 로 끝난 substage 를 verifier 가 VERIFIED 로 통과시키고 **바로 다음 게이트가 하드 차단**하는 정지가 발생했다 (issue #6-①). 파일은 멀쩡히 있으므로 "파일 존재" 검사로는 절대 잡히지 않는다.
+
+```bash
+DRAFT=$(bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".draft_path' | tr -d '"')
+{ [ -n "$DRAFT" ] && [ "$DRAFT" != "null" ]; } || REJECTED   # 마커 누락 — 파일이 있어도 REJECTED
+ROOT=$(bash <SCRIPTS_DIR>/state.sh root)
+if [[ "$DRAFT" == /* ]]; then DRAFT_ABS="$DRAFT"; else DRAFT_ABS="$ROOT/$DRAFT"; fi
+[ -f "$DRAFT_ABS" ] || REJECTED
+```
+
+REJECTED 시 `findings[].item` 은 `requirements.draft_path_missing`, `next_action` 은 `REVERT_DONE_MARKER`. 재작업하는 planner 는 `stages/02-requirements.md` §2-5 의 9번 항목(`draft_recorded`)을 채우면 된다.
+
+**게이트 · self_check · verifier 세 곳의 필수 마커 정의는 항상 일치해야 한다.** 한 곳만 고치면 같은 정지가 그대로 재현된다.
+
 ### 3. Sub-agent 출력 정합성 점검
 
 다음 *추론형* 의심 신호를 확인한다:
-- **빈 응답** — 산출물 언급 없이 "완료" 선언
+- **빈 응답** — 산출물 언급 없이 "완료" 선언.
+  **단, §1·§2 의 결정론적 검사를 전부 통과했다면 이 신호만으로 REJECTED 하지 않는다.** `dispatch_stage` 는 최종 텍스트가 없어도 `.done=true` 면 성공으로 처리한다 (`shouldOverrideEmptyOutcome` — 최종 텍스트를 생략하는 로컬 모델 보상). 그 보상과 이 신호가 어긋나 있으면 그런 모델에서는 **모든 substage 가 REJECTED** 된다 (issue #6 부수 관찰 1). 산출물과 마커가 결정론적으로 검증되는데 산문이 없다는 것은 실패의 증거가 아니다.
+  마커나 산출물이 하나라도 어긋나면 그때는 REJECTED 이지만, 그건 이 추론 신호가 아니라 **§1·§2 위반**으로 기록한다 (`findings[].item` 을 결정론적 항목명으로 적는다 — 원인을 "빈 응답" 으로 돌리면 재작업 방향이 어긋난다).
 - **테스트 삭제 정황** — output에 "기존 테스트 제거" / `// @ts-ignore` 추가 / `as any` 도입 언급
 - **인라인 disable** — `eslint-disable` / `# noqa` 등으로 게이트 우회
 - **자기선언 완료** — `done=true`를 임의로 기록했으나 self_check 누락

package/dist/opencode-plugin.js

@@ -25,7 +25,7 @@ import { computeVerdictHash } from "./verdict-hash.js";
 import { nextModel, applyConfigOverrides, POLICIES } from "./model-fallback-policy.js";
 import { agentForStage, STAGE_SPEC_FILES } from "./agent-stage-config.js";
 import { shouldEscalateStall } from "./stall-escalation.js";
-import { buildStateWriteBlockMessage, classifyStateJsonAccess, STATE_SH_CALL_RE } from "./state-access-guard.js";
+import { buildStateWriteBlockMessage, classifyStateJsonAccess, looksLikeRedirection, STATE_SH_CALL_RE, stripQuotedSpans, } from "./state-access-guard.js";
 import { RESEARCH_SOURCES, DEFAULT_RESEARCH_TIMEOUT_MINUTES, buildResearchPrompt, mergeResearchFindings, normalizeQueries, parseResearchOutput, resolveParallelism, summarizeOutcomes, } from "./research-fanout.js";
 import { TmuxMonitor, readTmuxConfig, orphanCleanupGuard } from "./tmux-monitor.js";
 import { resolvePaths, loadConfig, readLoggingConfig, DEFAULT_STALL_ESCALATE_THRESHOLD, } from "./config.js";
@@ -266,18 +266,27 @@ export function looksLikeFileWrite(cmd) {
         return false;
     if (STATE_SH_CALL_RE.test(cmd))
         return false;
+    // 리디렉션 계열은 인용 구간을 지운 문자열로 판정한다 — 따옴표 안의 `>` 는
+    // 셸 메타문자가 아니라 리터럴이다. `jq -e '… length >= 1'` 같은 읽기 전용
+    // 술어가 "파일 쓰기" 로 잡혀 analyzer 가 자기 산출물을 검증하지 못했다 (issue #6-③).
+    const bare = stripQuotedSpans(cmd);
+    // 셸 인라인 스크립트는 인용 구간이 사라지면 내부 리디렉션이 보이지 않는다 → 통째로 차단.
+    // 스크립트 파일 실행(`bash <SCRIPTS_DIR>/state.sh …`)은 `-c` 가 없어 매치되지 않는다.
+    if (/\b(?:ba|z|k|da)?sh\b\s+-\w*c\b/.test(cmd))
+        return true;
+    if (/(^|[|&;\s(`{])eval\s/.test(cmd))
+        return true;
     if (/(^|[|&;])\s*(tee|dd)\b/.test(cmd))
         return true;
     if (/\bsed\b[^|;&]*\s-i(?:\b|['"])/.test(cmd))
         return true;
-    if (/\bawk\b[^|;&]*?(?<![0-9])>\s*(?![&/])\S/.test(cmd))
-        return true;
-    if (/(^|[|;&\s])(cat|printf|echo)\b[^|;&]*?(<<\S+.*?)?(?<![0-9])>\s*(?![&/])\S/.test(cmd))
+    if (/\bawk\b[^|;&]*?(?<![0-9])>\s*(?![&/])\S/.test(bare))
         return true;
-    if (/(^|[|&;\s])>\s*(?!&|\/dev\/(?:null|stderr|stdout|tty)\b)\S/.test(cmd))
+    if (/(^|[|;&\s])(cat|printf|echo)\b[^|;&]*?(<<\S+.*?)?(?<![0-9])>\s*(?![&/])\S/.test(bare))
         return true;
-    if (/(^|[|&;\s])>>\s*(?!\/dev\/(?:null|stderr|stdout|tty)\b)\S/.test(cmd))
+    if (looksLikeRedirection(cmd))
         return true;
+    // 인터프리터 인라인 스크립트는 따옴표 *안* 을 봐야 하므로 원문으로 판정한다.
     if (/\bpython3?\s+-c\s+["'][^"']*open\s*\([^)]*["']\s*,\s*["'][wa]/.test(cmd))
         return true;
     if (/\bnode\s+-e\s+["'].*?(?:writeFileSync|writeFile\b|appendFileSync|createWriteStream)/.test(cmd))

package/dist/state-access-guard.d.ts

@@ -10,6 +10,42 @@ export declare const STATE_JSON_PATH_RE: RegExp;
 export declare const STATE_SH_SUBCOMMANDS: readonly ["root", "issue", "init", "status", "get", "set", "append", "migrate"];
 /** `state.sh <승인 서브커맨드>` 호출 탐지. 목록은 STATE_SH_SUBCOMMANDS 하나에서만 온다. */
 export declare const STATE_SH_CALL_RE: RegExp;
+/**
+ * 따옴표 안의 내용을 공백으로 덮는다 (따옴표 자체와 **문자 오프셋**은 보존).
+ *
+ * ── 배경 (issue #6-③) ──
+ * 셸에서 따옴표 안의 `>`·`|`·`;` 는 메타문자가 아니라 리터럴인데, 종전 판정은
+ * 명령 문자열 전체를 훑었다. 그래서 analyzer 가 자기 산출물을 검증하려고 실행한
+ *   jq -e '… and (.task_relevant_files | length >= 1)' …
+ * 의 `>=` 가 "출력 리디렉션" 으로, `|` 가 "파이프 세그먼트 경계" 로 잡혀
+ * 읽기 전용 술어가 3회 차단됐다 (리디렉션도 파이프도 없었다). `>=` 하나만 예외
+ * 처리하면 `awk '$1 > 2'`·`grep '>'` 같은 같은 계열이 계속 남는다 — 셸 문법을
+ * 그대로 모델링하는 쪽이 맞다.
+ *
+ * 길이를 보존하는 이유: 마스킹된 문자열에서 찾은 위치를 **원문에 그대로** 대응시켜
+ * 세그먼트를 잘라내기 위해서다 (`splitUnquotedSegments`).
+ *
+ * 보수적 처리 두 가지 — 오탐(막음)에는 우회로가 있지만 미탐(허용)은 복구 수단이 없다:
+ *   - 따옴표가 닫히지 않으면 그 지점부터 원문을 그대로 남긴다.
+ *   - 큰따옴표 안에 명령 치환(`$(` / 백틱)이 있으면 그 span 은 덮지 않는다.
+ *     큰따옴표 안에서는 치환이 실제로 실행되므로 `"$(cat a > b)"` 가 숨겨진다.
+ */
+export declare function stripQuotedSpans(cmd: string): string;
+/**
+ * 출력 리디렉션(`>` / `>>`) 탐지. `2>/dev/null`, `1>&2`, `>/dev/null` 은 제외한다.
+ *
+ * 인용 구간을 덮은 문자열로만 판정한다 — 따옴표 안의 `>` 는 리디렉션이 아니다.
+ * `looksLikeFileWrite`(leader/planner/analyzer 하드룰)와 아래 WRITE_INDICATORS 가
+ * 같은 함수를 쓴다. 한쪽만 고치면 다른 쪽에서 같은 오탐이 남는다.
+ */
+export declare function looksLikeRedirection(cmd: string): boolean;
+/**
+ * 인용 밖의 `;` `|` `&` `\n` 에서만 자른 **원문** 세그먼트.
+ *
+ * 종전에는 원문을 그대로 split 해서 `jq '.a | length'` 의 파이프가 세그먼트를
+ * 갈랐고, 뒷조각의 선두 토큰(`length`)이 읽기 allowlist 에 없어 차단됐다 (#6-③).
+ */
+export declare function splitUnquotedSegments(cmd: string): string[];
 export type StateAccessVerdict = 
 /** 명령에 state.json 경로가 없다 — 이 가드의 관심 밖. */
 {
@@ -34,7 +70,8 @@ export type StateAccessVerdict =
  *
  * 순서가 계약이다:
  *   1. 경로 없음 → unrelated
- *   2. 쓰기 지표 → write (state.sh 호출이 같이 있어도 차단)
+ *   2. 리디렉션(인용 구간 제외) → write
+ *   2'. 그 밖의 쓰기 지표 → write (state.sh 호출이 같이 있어도 차단)
  *   3. state.sh 승인 호출 → approved-helper
  *   4. state.json 을 언급하는 모든 세그먼트가 읽기 전용 allowlist → read-only
  *   5. 그 외 → write (모르는 명령은 차단)

package/dist/state-access-guard.js

@@ -38,6 +38,96 @@ export const STATE_SH_SUBCOMMANDS = [
 ];
 /** `state.sh <승인 서브커맨드>` 호출 탐지. 목록은 STATE_SH_SUBCOMMANDS 하나에서만 온다. */
 export const STATE_SH_CALL_RE = new RegExp(String.raw `state\.sh\s+(?:${STATE_SH_SUBCOMMANDS.join("|")})(?![\w-])`);
+/**
+ * 따옴표 안의 내용을 공백으로 덮는다 (따옴표 자체와 **문자 오프셋**은 보존).
+ *
+ * ── 배경 (issue #6-③) ──
+ * 셸에서 따옴표 안의 `>`·`|`·`;` 는 메타문자가 아니라 리터럴인데, 종전 판정은
+ * 명령 문자열 전체를 훑었다. 그래서 analyzer 가 자기 산출물을 검증하려고 실행한
+ *   jq -e '… and (.task_relevant_files | length >= 1)' …
+ * 의 `>=` 가 "출력 리디렉션" 으로, `|` 가 "파이프 세그먼트 경계" 로 잡혀
+ * 읽기 전용 술어가 3회 차단됐다 (리디렉션도 파이프도 없었다). `>=` 하나만 예외
+ * 처리하면 `awk '$1 > 2'`·`grep '>'` 같은 같은 계열이 계속 남는다 — 셸 문법을
+ * 그대로 모델링하는 쪽이 맞다.
+ *
+ * 길이를 보존하는 이유: 마스킹된 문자열에서 찾은 위치를 **원문에 그대로** 대응시켜
+ * 세그먼트를 잘라내기 위해서다 (`splitUnquotedSegments`).
+ *
+ * 보수적 처리 두 가지 — 오탐(막음)에는 우회로가 있지만 미탐(허용)은 복구 수단이 없다:
+ *   - 따옴표가 닫히지 않으면 그 지점부터 원문을 그대로 남긴다.
+ *   - 큰따옴표 안에 명령 치환(`$(` / 백틱)이 있으면 그 span 은 덮지 않는다.
+ *     큰따옴표 안에서는 치환이 실제로 실행되므로 `"$(cat a > b)"` 가 숨겨진다.
+ */
+export function stripQuotedSpans(cmd) {
+    const out = [];
+    let i = 0;
+    while (i < cmd.length) {
+        const ch = cmd[i];
+        if (ch !== "'" && ch !== '"') {
+            out.push(ch);
+            i++;
+            continue;
+        }
+        let close = -1;
+        for (let j = i + 1; j < cmd.length; j++) {
+            if (cmd[j] === "\\" && ch === '"') {
+                j++;
+                continue;
+            }
+            if (cmd[j] === ch) {
+                close = j;
+                break;
+            }
+        }
+        if (close < 0) {
+            // 미종료 따옴표 — 남은 전부를 원문으로 둔다 (메타문자가 계속 보이므로 차단 쪽).
+            out.push(cmd.slice(i));
+            break;
+        }
+        const body = cmd.slice(i + 1, close);
+        if (ch === '"' && /\$\(|`/.test(body)) {
+            // 큰따옴표 안의 명령 치환은 실제로 실행된다 → 덮지 않는다.
+            out.push(cmd.slice(i, close + 1));
+        }
+        else {
+            out.push(ch, " ".repeat(body.length), ch);
+        }
+        i = close + 1;
+    }
+    return out.join("");
+}
+/**
+ * 출력 리디렉션(`>` / `>>`) 탐지. `2>/dev/null`, `1>&2`, `>/dev/null` 은 제외한다.
+ *
+ * 인용 구간을 덮은 문자열로만 판정한다 — 따옴표 안의 `>` 는 리디렉션이 아니다.
+ * `looksLikeFileWrite`(leader/planner/analyzer 하드룰)와 아래 WRITE_INDICATORS 가
+ * 같은 함수를 쓴다. 한쪽만 고치면 다른 쪽에서 같은 오탐이 남는다.
+ */
+export function looksLikeRedirection(cmd) {
+    return /(?:^|[|&;\s(`{])>>?\s*(?!&|\/dev\/(?:null|stderr|stdout|tty)(?![\w/]))\S/
+        .test(stripQuotedSpans(cmd));
+}
+/** 세그먼트 구분자 — 인용 밖에서만 유효하다. */
+const SEGMENT_SPLIT_RE = /\|\||&&|[;|&\n]/g;
+/**
+ * 인용 밖의 `;` `|` `&` `\n` 에서만 자른 **원문** 세그먼트.
+ *
+ * 종전에는 원문을 그대로 split 해서 `jq '.a | length'` 의 파이프가 세그먼트를
+ * 갈랐고, 뒷조각의 선두 토큰(`length`)이 읽기 allowlist 에 없어 차단됐다 (#6-③).
+ */
+export function splitUnquotedSegments(cmd) {
+    const masked = stripQuotedSpans(cmd);
+    const segments = [];
+    let start = 0;
+    SEGMENT_SPLIT_RE.lastIndex = 0;
+    let m;
+    while ((m = SEGMENT_SPLIT_RE.exec(masked)) !== null) {
+        segments.push(cmd.slice(start, m.index));
+        start = m.index + m[0].length;
+    }
+    segments.push(cmd.slice(start));
+    return segments;
+}
 /**
  * 쓰기 의도 지표. 하나라도 매칭되면 명령 전체를 차단한다.
  *
@@ -45,14 +135,17 @@ export const STATE_SH_CALL_RE = new RegExp(String.raw `state\.sh\s+(?:${STATE_SH
  * 승인된 호출에 쓰기를 끼워 넣는 밀수 경로를 막기 위해서다.
  */
 const WRITE_INDICATORS = [
-    // `>` / `>>` 리디렉션. `2>/dev/null`, `1>&2`, `>/dev/null` 은 제외한다.
-    [/(?:^|[|&;\s(`{])>>?\s*(?!&|\/dev\/(?:null|stderr|stdout|tty)(?![\w/]))\S/, "출력 리디렉션 (> / >>)"],
     [/(?:^|[|&;(`{])\s*(?:tee|dd|sponge)\b/, "tee / dd / sponge"],
     [/\bsed\b[^|;&]*\s-i(?:\b|['"])/, "sed -i (in-place 편집)"],
     [/\b(?:perl|ruby)\b[^|;&]*\s-\w*i\b/, "perl / ruby -i (in-place 편집)"],
     // 인터프리터 인라인 스크립트는 읽기/쓰기를 정적으로 구분할 수 없다 → 전부 차단.
     // 읽기가 필요하면 cat / jq / head 를 쓴다.
     [/\b(?:python3?|node|bun|deno|ruby|perl|php)\b\s+-\w*[ce]\b/, "인터프리터 인라인 스크립트 (-c / -e)"],
+    // 셸 인라인 스크립트도 정적으로 분해할 수 없다. 인용 구간을 지우면서(#6-③)
+    // `bash -c 'echo x > f'` 의 리디렉션이 보이지 않게 되므로 여기서 함께 막는다.
+    // 스크립트 파일 실행(`bash <SCRIPTS_DIR>/state.sh …`)은 `-c` 가 없어 매치되지 않는다.
+    [/\b(?:ba|z|k|da)?sh\b\s+-\w*c\b/, "셸 인라인 스크립트 (sh -c)"],
+    [/(?:^|[|&;\s(`{])eval\s/, "eval"],
     [/(?:^|[|&;\s(`{])(?:cp|mv|rm|ln|install|touch|truncate|shred|chmod|chown|unlink|rsync|mkfifo)\s/, "파일 조작 명령"],
     [/\bgit\b(?:\s+-\S+(?:\s+\S+)?)*\s+(?:add|rm|mv|checkout|restore|stash|apply|clean|update-index|reset|commit)\b/, "git 쓰기 서브커맨드"],
     [/(?:^|[|&;\s(`{])(?:vi|vim|nano|emacs|ed|ex|patch)\s/, "편집기 / patch"],
@@ -75,7 +168,6 @@ const READ_ONLY_GIT_SUBCOMMANDS = new Set([
 const GIT_OPTIONS_WITH_VALUE = new Set([
     "-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path",
 ]);
-const SEGMENT_SPLIT_RE = /\|\||&&|[;|&\n]/;
 /** 세그먼트 선두의 괄호·역따옴표·환경변수 대입을 벗겨 실제 명령 토큰을 얻는다. */
 function segmentHead(segment) {
     let s = segment;
@@ -112,7 +204,8 @@ function gitSubcommand(rest) {
  *
  * 순서가 계약이다:
  *   1. 경로 없음 → unrelated
- *   2. 쓰기 지표 → write (state.sh 호출이 같이 있어도 차단)
+ *   2. 리디렉션(인용 구간 제외) → write
+ *   2'. 그 밖의 쓰기 지표 → write (state.sh 호출이 같이 있어도 차단)
  *   3. state.sh 승인 호출 → approved-helper
  *   4. state.json 을 언급하는 모든 세그먼트가 읽기 전용 allowlist → read-only
  *   5. 그 외 → write (모르는 명령은 차단)
@@ -120,6 +213,8 @@ function gitSubcommand(rest) {
 export function classifyStateJsonAccess(cmd) {
     if (!STATE_JSON_PATH_RE.test(cmd))
         return { kind: "unrelated" };
+    if (looksLikeRedirection(cmd))
+        return { kind: "write", reason: "출력 리디렉션 (> / >>)" };
     for (const [re, reason] of WRITE_INDICATORS) {
         if (re.test(cmd))
             return { kind: "write", reason };
@@ -127,7 +222,7 @@ export function classifyStateJsonAccess(cmd) {
     if (STATE_SH_CALL_RE.test(cmd))
         return { kind: "approved-helper" };
     const readers = [];
-    for (const segment of cmd.split(SEGMENT_SPLIT_RE)) {
+    for (const segment of splitUnquotedSegments(cmd)) {
         if (!STATE_JSON_PATH_RE.test(segment))
             continue;
         const { head, rest } = segmentHead(segment);

package/gates/stage3-scope-verify.sh

@@ -36,8 +36,21 @@ SPEC_HASH="$(q '.stages."1_planning".substages."requirements".spec_hash')"
 if [ "$SPEC_HASH" != "__MISSING__" ] && [ "$SPEC_HASH" != "null" ] && [ -n "$SPEC_HASH" ]; then
   DRAFT="$(q '.stages."1_planning".substages."requirements".draft_path')"
   ROOT="$("$HERE/../scripts/state.sh" root)"
-  { [ "$DRAFT" != "__MISSING__" ] && [ "$DRAFT" != "null" ] && [ -f "$ROOT/$DRAFT" ]; } \
-    || fail "spec_hash 기록됨 그러나 확정 명세 파일 없음 (draft_path=$DRAFT)"
+  # 마커 누락과 파일 부재를 구분해서 알린다. 종전에는 둘 다 "확정 명세 파일 없음" 으로
+  # 뭉뚱그려서, 파일은 멀쩡히 있고 마커만 빠진 흔한 경우(issue #6-①)에 무엇을 해야
+  # 하는지 알 수 없었다. 마커 기록은 team-leader 에게 허용된 state.sh set 경로다.
+  DEFAULT_DRAFT=".makdoong2-team/${ISSUE}/requirements-draft.md"
+  if [ "$DRAFT" = "__MISSING__" ] || [ "$DRAFT" = "null" ] || [ -z "$DRAFT" ]; then
+    if [ -f "$ROOT/$DEFAULT_DRAFT" ]; then
+      fail "spec_hash 는 기록됐는데 draft_path 마커가 없다 — 파일은 ${DEFAULT_DRAFT} 에 있다.
+  복구: (1) sha256sum \"${ROOT}/${DEFAULT_DRAFT}\" 가 spec_hash(${SPEC_HASH}) 와 같은지 대조하고,
+        (2) 같으면 state.sh set 으로 requirements.draft_path 에 \"${DEFAULT_DRAFT}\" 를 기록한다 (stages/02-requirements.md §2-0),
+        (3) 다르면 명세가 동결 후 변경된 것이므로 requirements substage 를 재작업한다 (§2-4a)."
+    fi
+    fail "spec_hash 는 기록됐는데 draft_path 마커도 확정 명세 파일도 없다 — requirements substage 를 재작업하라 (stages/02-requirements.md §2-0, §2-5 9번)"
+  fi
+  [ -f "$ROOT/$DRAFT" ] \
+    || fail "draft_path=${DRAFT} 마커는 있으나 파일이 없다 (기준 경로 ${ROOT}) — worktree 동기화 누락이거나 파일이 삭제됐다"
   ACTUAL="$(sha256sum "$ROOT/$DRAFT" | cut -d' ' -f1)"
   [ "$ACTUAL" = "$SPEC_HASH" ] \
     || fail "확정 명세 무단 변경 감지 (spec drift) — 동결 후 변경은 사용자 재승인 + spec_hash 재기록 절차만 허용 (stages/02-requirements.md §2-4a)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makdoong2-team",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/lib/git-exclude.sh

@@ -0,0 +1,60 @@
+# git-exclude.sh — `.git/info/exclude` 에 패턴을 등록하는 공용 헬퍼.
+# source 전용 (직접 실행하지 않는다).
+#
+# ── 배경 (issue #6-②) ──
+# 플러그인은 자기 상태를 작업 트리 안(`.makdoong2-team/`)에 만들면서 git exclude 에는
+# 등록하지 않았다. 그래서 그 패턴이 `.gitignore` 에도 `.git/info/exclude` 에도 없는
+# 저장소에서는 `git status --porcelain` 이 항상 `?? .makdoong2-team/` 를 보고했고,
+# "git status 청결" 을 요구하는 `2_implementation.analysis` verifier 가 **항상
+# REJECTED** 를 냈다 (산출물·마커는 전부 정상인데도).
+#
+# 더 나쁜 것은 그 시점에 exclude 를 고칠 권한을 가진 역할이 파이프라인에 없다는 점이다:
+#   - analyzer  : write 권한이 산출물 1개로 제한
+#   - team-leader: 하드룰 2 훅이 bash 파일 쓰기를 차단
+#   - engineer  : `2_implementation.dev` 단계라 analysis 를 통과해야 도달
+# 결국 동일 사유 REJECTED 가 무한 반복되고 사용자가 직접 한 줄을 넣어야 풀렸다.
+#
+# ── 왜 wt-sync-ignored.sh 의 ensure_baseline_gitexclude() 만으로는 부족한가 ──
+# 그 함수는 **worktree 생성(= dev 진입) 시점에만** 돈다. plugin 의 wt-sync 호출은
+# 전부 `DEV_OR_LATER_STAGES` / `worktree !== cwd` 로 가드되어 있다. analysis 는
+# 그보다 앞선 main repo 단계라 그때는 한 번도 실행되지 않았다. 그래서 상태 디렉터리를
+# **처음 만드는** `state.sh init` 에서도 등록한다.
+#
+# `.git/info/exclude` 는 커밋되지 않는 로컬 파일이라 대상 저장소의 이력을 건드리지 않는다.
+# worktree 의 `--git-common-dir` 은 main repo 의 `.git` 을 가리키므로 한 번 등록하면
+# main repo 와 모든 worktree 가 함께 적용받는다.
+
+# 플러그인이 작업 트리 안에 만드는 자기 상태 디렉터리. 이 상수가 유일한 출처다.
+MAKDOONG2_STATE_DIR_PATTERN=".makdoong2-team/"
+
+# ensure_git_exclude_lines <repo-dir> <pattern>...
+#   없는 라인만 append 한다. 추가한 개수를 stdout 으로 출력한다.
+#   git 저장소가 아니거나 파일을 쓸 수 없으면 0 을 출력하고 **성공으로 끝낸다** —
+#   호출부(state.sh init 등)는 `set -e` 아래에서 돌고, exclude 등록 실패가
+#   워크플로우 시작 자체를 막아서는 안 된다.
+ensure_git_exclude_lines() {
+  local dir=$1
+  shift || true
+  [ "$#" -gt 0 ] || { echo 0; return 0; }
+
+  local common
+  common="$(git -C "${dir}" rev-parse --git-common-dir 2>/dev/null)" || { echo 0; return 0; }
+  [ -n "${common}" ] || { echo 0; return 0; }
+  if [[ "${common}" != /* ]]; then
+    common="$(cd "${dir}/${common}" 2>/dev/null && pwd -P)" || { echo 0; return 0; }
+    [ -n "${common}" ] || { echo 0; return 0; }
+  fi
+
+  local file="${common}/info/exclude"
+  mkdir -p "${common}/info" 2>/dev/null || { echo 0; return 0; }
+  touch "${file}" 2>/dev/null || { echo 0; return 0; }
+
+  local added=0 ln
+  for ln in "$@"; do
+    [ -n "${ln}" ] || continue
+    if ! grep -qxF -- "${ln}" "${file}" 2>/dev/null; then
+      printf '%s\n' "${ln}" >> "${file}" 2>/dev/null && added=$((added + 1))
+    fi
+  done
+  echo "${added}"
+}

package/scripts/run-tests.mjs

@@ -39,6 +39,7 @@ const STEPS = [
   "node test/skill-mcp-registry.test.mjs",
   "node --test test/state-write-guard.test.mjs",
   "node --test test/state-access-guard.test.mjs",
+  "node --test test/git-exclude-registration.test.mjs",
   "node --test test/issue-reporter-guard.test.mjs",
   "node --test test/release-confirm.test.mjs",
   "node --test test/state-sh-schema.test.mjs",

package/scripts/state.sh

@@ -28,6 +28,10 @@
 # 의존: jq
 set -euo pipefail
 
+# 플러그인 자기 상태 디렉터리를 git exclude 에 등록하기 위한 공용 헬퍼 (issue #6-②).
+# shellcheck source=lib/git-exclude.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/git-exclude.sh"
+
 root()  {
   # 호출 컨텍스트의 git toplevel 을 반환한다.
   # - main repo에서 호출: main repo 경로
@@ -92,6 +96,12 @@ case "$cmd" in
   init)
     ISSUE="${1:?issue required}"; WT="${2:-$(root)}"
     P="$(sp "$ISSUE")"; mkdir -p "$(dirname "$P")"
+    # 상태 디렉터리를 만드는 바로 그 자리에서 git exclude 에 등록한다. 여기서 하지
+    # 않으면 `git status` 가 플러그인 자신의 파일을 보고하고, "git status 청결" 을
+    # 요구하는 2_implementation.analysis verifier 가 항상 REJECTED 를 낸다 (issue #6-②).
+    # 이 시점(main repo)은 worktree 생성 전이라 wt-sync-ignored.sh 가 아직 돌지 않는다.
+    ADDED_EXCLUDE="$(ensure_git_exclude_lines "$(root)" "${MAKDOONG2_STATE_DIR_PATTERN}")"
+    [ "${ADDED_EXCLUDE}" = "0" ] || echo "[state.sh] .git/info/exclude += ${MAKDOONG2_STATE_DIR_PATTERN}" >&2
     if [ ! -f "$P" ]; then
       cat > "$P" <<JSON
 {

package/scripts/wt-sync-ignored.sh

@@ -11,6 +11,9 @@
 #     예: "worktree": { "extra_exclude": ".idea/:tmp/" }
 set -euo pipefail
 
+# shellcheck source=lib/git-exclude.sh
+. "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/git-exclude.sh"
+
 # --reverse: worktree → main repo 역방향 동기화 (issue-scoped .makdoong2-team/<issue>/ 만)
 REVERSE=false
 while [[ "${1:-}" == --* ]]; do
@@ -130,24 +133,13 @@ fi
 # 이미 존재하는 라인은 skip 하여 사용자 편집을 덮어쓰지 않는다.
 ensure_baseline_gitexclude() {
   local wt=$1
-  local git_common_dir
-  git_common_dir="$(git -C "$wt" rev-parse --git-common-dir 2>/dev/null)"
-  if [ -z "$git_common_dir" ]; then
-    echo "[wt-sync-ignored] git-common-dir 식별 실패, exclude 스킵" >&2
-    return 0
-  fi
-  if [[ "$git_common_dir" != /* ]]; then
-    git_common_dir="$(cd "$wt/$git_common_dir" 2>/dev/null && pwd -P)" || {
-      echo "[wt-sync-ignored] git-common-dir 절대경로 변환 실패" >&2
-      return 0
-    }
-  fi
-  local exclude_file="$git_common_dir/info/exclude"
-  mkdir -p "$(dirname "$exclude_file")"
-  local added=0
   local -a lines=()
 
   # 공통 (모든 프로젝트)
+  # 플러그인 자신의 상태 디렉터리를 맨 앞에 둔다 — 이게 빠져 있으면 analysis verifier 가
+  # 항상 REJECTED 를 낸다 (issue #6-②). state.sh init 에서도 등록하지만, 이미 state.json 이
+  # 있어 init 의 등록 경로를 타지 않은 기존 워크플로우는 여기서 뒤늦게 구제된다.
+  lines+=("${MAKDOONG2_STATE_DIR_PATTERN}")
   lines+=(".DS_Store" "Thumbs.db" "*.log" "*.swp")
 
   # Python
@@ -175,16 +167,9 @@ ensure_baseline_gitexclude() {
     lines+=("vendor/" "*.test" "*.out")
   fi
 
-  # 존재하지 않는 라인만 append
-  touch "$exclude_file"
-  local ln
-  for ln in "${lines[@]}"; do
-    if ! grep -qxF -- "$ln" "$exclude_file" 2>/dev/null; then
-      printf '%s\n' "$ln" >> "$exclude_file"
-      added=$((added+1))
-    fi
-  done
-
+  # append 는 공용 헬퍼가 한다 (git-common-dir 해석·중복 검사 포함).
+  local added
+  added="$(ensure_git_exclude_lines "$wt" "${lines[@]}")"
   if [ "$added" -gt 0 ]; then
     echo "[wt-sync-ignored] baseline .git/info/exclude +$added lines (project-type detected)"
   fi

package/skills/makdoong2-issue-reporter/SKILL.md

@@ -22,7 +22,7 @@ makdoong2-team 플러그인의 결함을 재현 가능한 형태로 GitHub 이
 - 사용자에게 "무슨 문제였나요"를 먼저 묻지 않는다. 호출 자체가 "직전에 뭔가 잘못됐으니 조사해서 남겨라"라는 지시다.
 - 사용자가 증상을 한 줄만 말하거나 아무 설명 없이 호출해도 동작해야 한다. 부족한 정보는 질의가 아니라 **수집과 분석으로 먼저 메운다**.
 - 질의(4장)는 수집·분석으로 확정할 수 없는 항목(기대 동작, 재현성, 시도한 조치)과 **분석 결과 확인**에만 사용한다.
-- 실행 순서는 고정한다: **수집(3장) → 이상 지점 포착(3.3) → 마스킹(2장) → 중복 확인(5장) → 최소 질의(4장) → 이슈 생성(7장)**.
+- 실행 순서는 고정한다: **수집(3장) → 이상 지점 포착(3.3) → 마스킹(2장) → 중복 확인(5장) → 최소 질의(4장) → 본문 작성(6장) → 이슈 생성(7장)**.
 
 ## 0. 대상 리소스
 
@@ -130,6 +130,8 @@ test -n "$GH_TOKEN" || echo "NO_TOKEN"
 | 모델·프로바이더 사내 엔드포인트 | 사내 모델 서버 주소 | `<internal-model-endpoint>` |
 | 토큰 유사 문자열 | `ghp_...`, `eyJ...`(JWT) | `<redacted-token>` |
 
+같은 원본은 항상 같은 자리표시자로, 다른 원본은 다른 자리표시자로 쓴다. **같은 종류가 둘 이상이면 접미사로 구분한다** — `<internal-repo-A>` / `<internal-repo-B>`. 둘을 한 이름으로 뭉치면 "두 프로젝트에서 같은 증상" 과 "한 프로젝트에서 두 번" 이 구별되지 않아 재현 조건이 무너진다.
+
 ### 2.3 절차
 
 1. 첨부 후보 텍스트를 모은 뒤, **첨부 직전에** 마스킹 스캔을 1회 수행한다.
@@ -325,101 +327,241 @@ curl -sS -X POST https://api.github.com/repos/y00njinuk/makdoong2-team/issues/<n
 
 > 코멘트 추가도 GitHub 쓰기이므로 7-1 의 사용자 승인 게이트를 동일하게 거친다.
 
-기존 열린 이슈(2026-08-26 기준):
+**열린 이슈 목록을 이 문서에 하드코딩하지 않는다.** 스냅샷은 곧 낡고, 삭제·이관된 이슈를 가리키면 중복 판정 자체가 어긋난다(과거 이 자리에 있던 #1·#4 표가 그렇게 됐다 — 두 이슈는 현재 `410 Gone` 이다). 목록은 매 실행 시 위 검색으로 얻는다.
 
-| # | 제목 요약 | 영역 | 링크 |
-|---|---|---|---|
-| 4 | `1_planning.jira` 단계 반복 실패 | 워크플로 단계 | https://github.com/y00njinuk/makdoong2-team/issues/4 |
-| 1 | 서브에이전트 호출 시 조건과 무관한 프롬프트 injection | 오케스트레이션/프롬프트 | https://github.com/y00njinuk/makdoong2-team/issues/1 |
+판정 기준:
+
+| 판정 | 조건 | 처리 |
+|---|---|---|
+| 동일 | 실패 지점(에이전트 + 단계)과 근본 증상이 모두 같다 | 신규 생성 대신 **코멘트** |
+| 유사 | 증상은 닮았으나 실패 지점 또는 재현 경로가 다르다 | 신규 생성 + 본문에 관련 이슈 링크 |
+| 무관 | 위 둘 다 아니다 | 신규 생성 |
 
-동일 단계(`1_planning.jira`)나 동일 injection 증상은 신규 이슈보다 위 이슈에 코멘트로 축적하는 것이 우선이다.
+**닫힌 이슈도 검색 대상이다** (`is:open` 을 빼고 한 번 더 조회한다). 이미 고쳐진 결함의 재발이면 그 사실 자체가 가장 중요한 정보이므로, 신규 이슈보다 원 이슈에 코멘트로 재발을 알리고 어떤 버전에서 다시 났는지 명시한다.
+
+코멘트로 축적할 때도 6장 양식을 그대로 쓴다. 원 이슈와 동일한 항목(환경·재현 절차)은 `#<번호> 와 동일` 로 적고 **차이점과 새 증거만** 덧붙인다.
 
 ---
 
-## 6. 이슈 본문 템플릿
+## 6. 이슈 양식 (본문 작성 가이드)
+
+**이슈는 유지보수자가 그대로 진단에 쓸 수 있는 형태여야 한다.** 기준 사례는 [#5](https://github.com/y00njinuk/makdoong2-team/issues/5) 다 — 처리 코멘트가 타임라인·로그 발췌·반복 차단 표·의심 코드 지목을 지목하며 "그대로 진단에 쓰였다" 고 밝혔고, 본문 `## 제안` 3건이 항목별로 수정에 반영됐다. 아래 양식은 그 이슈가 실제로 갖췄던 구성을 규약으로 고정한 것이다.
 
-제목: 기존 이슈(#1, #4)의 규칙을 따른다. 접두 태그 없이, **어디서 무엇이 어떻게 잘못되는지**를 담은 한국어 서술형 한 문장으로 작성한다.
+**증상 한 줄 + 로그 덤프는 이 양식이 아니다.** 3장에서 수집·포착한 것을 아래 구조에 배치하는 것이 이 스킬의 산출물이다.
 
-- 기존 예: `1_planning.jira 단계에서 반복적으로 실패가 발생하는 이슈`
-- 기존 예: `서브에이전트 호출할 때 조건에 상관없이 불필요하게 특정 프롬프트가 인입(injection) 되는 현상`
+### 6.0 공통 원칙 (모든 섹션에 적용)
+
+| 원칙 | 의미 |
+|---|---|
+| **출처 없는 인용 금지** | 모든 코드블록·표 인용에 출처를 단다 — 파일 경로 + 라인 번호(`opencode.log line 19618`), 또는 세션 ID + 턴 번호. 출처 없는 발췌는 유지보수자가 원본을 되짚을 수 없어 가치가 절반이 된다 |
+| **관측과 추정의 분리** | 로그·응답으로 확인한 것만 단정형으로 쓴다. 추정은 `> 추정:` 블록쿼트에 넣고 근거와 "추정이며 단정은 아님" 을 함께 적는다 (3.3 판정 규칙과 동일) |
+| **재현 가능성 우선** | 제3자가 재현 절차만 읽고 같은 상태를 만들 수 있어야 한다. 비정상으로 보이는 전제가 있으면 **"왜 그 상태였는지"** 를 함께 적는다 — 결함이 아닌 것을 결함으로 오인시키지 않기 위해서다 |
+| **마스킹은 1:1 대응** | 같은 원본은 항상 같은 자리표시자로, 다른 원본은 다른 자리표시자로 쓴다. 같은 종류가 둘 이상이면 접미사로 구분한다 (`<internal-repo-A>` / `<internal-repo-B>`). 본문 끝 고지 2줄은 생략 불가 |
 
-제목에도 사내 식별자(고객사명, 사내 시스템명, 실제 Jira 키)를 넣지 않는다. 심각도·에이전트명은 본문 표에 기재한다.
+### 6.1 제목
+
+접두 태그·이슈 번호·심각도 없이 **한국어 서술형 한 문장**으로 쓴다. 구성은 `<어디서> + <무엇이 어떻게 잘못되어> + <그 결과>` 이고 `현상` 또는 `이슈` 로 끝맺는다.
+
+기준 예(#5):
+
+> state.json hardrule 훅이 읽기 전용 진단 명령까지 차단하여 state_unreadable 이후 복구 절차가 막히는 현상
+
+| 조각 | 해당 부분 |
+|---|---|
+| 어디서 | `state.json hardrule 훅이` |
+| 무엇이 어떻게 | `읽기 전용 진단 명령까지 차단하여` |
+| 그 결과 | `state_unreadable 이후 복구 절차가 막히는 현상` |
+
+규칙:
+
+- 사내 식별자(고객사명, 사내 시스템·저장소명, 실제 Jira 키)를 넣지 않는다. 제목도 본문과 **동일하게** 2장 규칙을 받는다.
+- 커밋 제목의 50자 제한은 **적용하지 않는다** — 증상이 특정되는 길이를 우선한다. 다만 한 문장을 넘기지 않는다.
+- **결과를 빼지 않는다.** `훅이 명령을 차단하는 현상` 은 무엇이 막혔는지가 없어 유지보수자가 우선순위를 매길 수 없다.
+- **원인을 제목에 단정하지 않는다.** 원인은 `> 추정:` 과 `## 참고: 의심 근본 원인 코드` 의 몫이다. 제목은 관측된 현상만 담는다.
+
+### 6.2 섹션 구성
+
+**순서 고정.** 필수 섹션은 내용이 없어도 생략하지 않고 `없음` / `미확인` 을 적는다. 조건부 섹션은 해당 사실이 있을 때만 넣고, 없으면 헤딩째 뺀다(빈 섹션을 남기지 않는다).
+
+| # | 섹션 | 구분 | 담는 것 |
+|---|---|---|---|
+| 1 | `## 증상` | 필수 | 한두 문장 요약. 핵심 메커니즘만 굵게 |
+| 2 | `## 환경` | 필수 | 표 — 버전·OS·런타임·모델·발생 시각·세션 ID |
+| 3 | `## 재현 절차` | 필수 | 번호 매긴 단계. 각 단계의 입력과 관측된 반환값 |
+| 4 | `## 기대 동작` | 필수 | 정상이라면 어떠해야 하는지 **+ 그 근거** |
+| 5 | `## 실제 동작` | 필수 | 관측된 결과. 에이전트 자신의 오판도 포함 |
+| 6 | `## 실패 지점` | 필수 | 관련 에이전트 / 단계 / 연동 경로 / 프롬프트 이상 4줄 |
+| 7 | `## 타임라인 (수집 구간: …)` | 필수 | 표 + `> 추정:` |
+| 8 | `## 에러 메시지` | 필수 | 번호 매긴 다목록. 항목마다 출처 |
+| 9 | `## 재현성 / 영향 범위` | 필수 | 재현 조건(결정적인가)과 파급 범위 |
+| 10 | `## 시도한 조치` | 필수 | 없으면 `없음` |
+| 11 | `## 관련 관찰: <요약>` | 조건부 | 같은 증상이 과거·다른 프로젝트에서 반복된 기록 |
+| 12 | `## 참고: 의심 근본 원인 코드 (<버전>, <파일>)` | 조건부 | 설치된 코드에서 원인 후보를 지목할 수 있을 때 |
+| 13 | `## 부수 관찰 (minor)` | 조건부 | 본 결함과 별개지만 같은 조사에서 발견한 사소한 문제 |
+| 14 | `## 제안 (참고)` | 조건부 | 수정 방향. 번호 매긴 목록 |
+| 15 | `## 증거` | 필수 | `<details>` 블록 + 마스킹 고지 2줄 |
+
+**11–14 는 "여유 있으면 쓰는 것" 이 아니다.** 3장 수집에서 근거가 나왔는데도 빼면 유지보수자가 같은 조사를 처음부터 다시 한다. #5 는 넷을 모두 채웠고 처리 코멘트가 항목별로 그것을 인용했다. 반대로 **근거 없이 채우지도 않는다** — 추측으로 만든 `## 제안` 은 진단을 잘못된 방향으로 끈다.
+
+### 6.3 본문 템플릿
 
 ~~~markdown
 ## 증상
-<한두 문장 요약>
+<한두 문장. "무엇이 어떤 조건에서 어떻게 되어 무엇이 막혔는가". 핵심 메커니즘만 굵게>
 
 ## 환경
 | 항목 | 값 |
 |---|---|
 | OpenCode | <version> |
-| omo | <version> |
-| makdoong2-team | <branch>@<commit> |
-| OS | <os> (WSL2: yes/no) |
-| Runtime | node <ver> / bun <ver> |
+| omo (oh-my-openagent) | <version> |
+| makdoong2-team | v<설치 버전> (commit <short-sha>) |
+| OS | <os> (WSL2 여부·커널 포함) |
+| Runtime | node <ver> (bun <ver> 또는 "bun 미설치") |
 | Provider / Model | <provider> / <model> |
-| 발생 시각 | <ISO8601> |
+| 발생 시각 | <ISO8601 KST> (<ISO8601 UTC>) |
 | 세션 ID | <session-id> |
 
 ## 재현 절차
-1.
-2.
-3.
+1. <초기 상태와 그 상태가 된 경위>
+2. <실행한 조작 — 프롬프트·커맨드 원문>
+3. <관측된 반환값·응답>
+4. <이상이 나타난 지점>
 
 ## 기대 동작
-<...>
+- <정상이라면 어떠해야 하는가>
+- <그렇게 판단하는 근거 — 문서·에러 메시지 문구·기존 계약>
 
 ## 실제 동작
-<...>
+- <관측된 결과>
+- <에이전트의 오판이 있었다면 그것도>
 
 ## 실패 지점
-- 관련 에이전트: <...>
-- 단계: <1_planning.jira 등 단계명>
-- 연동 경로: <Teams / MCP / 없음>
-- 프롬프트 이상: <injection / 누락 / 중복 / 없음>
+- 관련 에이전트: <이름 또는 unknown>
+- 단계: <1_planning.jira 등 단계명. 해당 없으면 "요청 분배 / 오케스트레이션">
+- 연동 경로: <Teams / MCP / Jira / 없음(로컬 플러그인 훅) — 구체 지점까지>
+- 프롬프트 이상: <injection / 누락 / 중복 / 없음 — 아니면 "없음" 과 그 근거>
 
-## 타임라인 (수집 구간: <T-2h> ~ <T>)
-| 시각 | 지점 | 관측 내용 |
+## 타임라인 (수집 구간: <시작> ~ <끝>)
+| 시각 (KST) | 지점 | 관측 내용 |
 |---|---|---|
+| <ts> | 세션 시작 | <...> |
 | <ts> | 마지막 정상 단계 | <...> |
 | <ts> | **최초 이상 발생** | <...> |
 | <ts> | 파급 | <...> |
 
-> 추정: <원인 추정. 추정임을 명시. 근거 없으면 "미상">
+> 추정: <원인 추정 + 근거. 근거의 출처(코드 독해/로그 패턴)와 "단정은 아님" 을 명시. 근거가 없으면 "미상">
 
 ## 에러 메시지
+1. <어디서 나온 무엇인지 — 예: `auto_advance_stage` 반환값 (JSON 필드 전문, 경로 마스킹)>
+```
+<원문>
+```
+
+2. <두 번째 메시지 — 예: 훅 차단 로그 (`/var/log/opencode/opencode.log` line <N>)>
 ```
-<마스킹된 원문>
+<원문>
 ```
 
 ## 재현성 / 영향 범위
-- 재현성: <항상 / 간헐적(n회 중 m회) / 1회성>
-- 영향 범위: <...>
+- 재현성: <항상(결정적 — 조건 명시) / 간헐적(n회 중 m회) / 1회성>
+- 영향 범위: <어느 에이전트·단계·기능까지 번지는가>
 
 ## 시도한 조치
-- <...>
+- <이미 해본 우회·수정과 그 결과. 없으면 "없음">
 
-## 증거
-<details>
-<summary>opencode.log 발췌 (라인 &lt;start&gt;-&lt;end&gt;, 마스킹 처리됨)</summary>
+## 관련 관찰: <요약> (조건부)
+| 시각 | 에이전트 | 관측 |
+|---|---|---|
+| <ts> | <agent> | <...> |
 
+## 참고: 의심 근본 원인 코드 (<버전>, <파일>) (조건부)
+```<lang>
+<해당 코드 발췌>
 ```
-<log>
-```
-</details>
+- <왜 이것이 의심되는가>
+- <설치본 코드 독해 기반 추정임을 명시>
 
+## 부수 관찰 (minor) (조건부)
+<본 결함과 별개지만 같은 조사에서 발견한 사소한 문제>
+
+## 제안 (참고) (조건부)
+1. <수정 방향 A>
+2. <수정 방향 B>
+
+## 증거
 <details>
-<summary>서브에이전트 프롬프트 발췌 (세션 &lt;id&gt;, 마스킹 처리됨)</summary>
+<summary>opencode.log 발췌 (lines N–M, 경로·이슈키 마스킹됨)</summary>
 
 ```
-<prompt>
+<log>
 ```
 </details>
 
-> 마스킹 내역: <가린 항목 종류와 건수>
+> 마스킹 내역: <가린 항목 종류와 건수. 스캔으로 확인한 "포함되지 않음" 도 함께>
 > 마스킹으로 생략된 정보: <있으면 기재, 없으면 "없음">
 ~~~
 
+### 6.4 섹션별 작성 규칙
+
+**`## 증상`** — 조건·메커니즘·결과가 한 덩어리로 읽혀야 한다. 굵게는 원인 메커니즘 한 곳에만 쓴다(전부 굵으면 강조가 사라진다). "안 됩니다"·"이상합니다" 같은 체감 표현 대신 관측 가능한 서술로 쓴다.
+
+**`## 환경`** — 4.2 의 자동 수집 결과를 그대로 옮긴다. makdoong2-team 은 **설치된 버전**을 쓴다(개발 중인 HEAD 가 아니라). 사용자가 구버전을 쓰고 있으면 그 사실이 곧 답인 경우가 있다. 사내 모델 엔드포인트는 마스킹하되 provider/model 이름 자체는 남긴다.
+
+**`## 재현 절차`** — 각 단계에 **입력과 관측된 반환값**을 함께 적는다. 비정상으로 보이는 전제(파일 부재, 이상한 설정)가 있으면 괄호로 경위를 밝힌다 — #5 의 `(state 파일 부재는 사용자의 의도적 삭제이며, 데이터 손실·동기화 실패가 아님)` 이 그 예다. 이 한 줄이 없으면 유지보수자는 "동기화 버그" 를 먼저 쫓는다.
+
+**`## 기대 동작`** — 기대만 쓰고 근거를 빼지 않는다. 근거는 문서 문구, 에러 메시지가 스스로 열거한 범위, 기존 계약 중 하나를 인용한다. #5 는 "훅의 에러 메시지 자체가 금지 대상으로 쓰기만 열거한다" 를 근거로 들어 기대가 임의 요구가 아님을 보였다.
+
+**`## 실제 동작`** — 결과와 함께 **에이전트 자신의 오판**도 적는다. #5 는 leader 가 차단 사유를 "하드룰 2 위반" 으로 잘못 인용한 것을 기록했고, 그것이 별도의 수정 항목(오인 유발 메시지 개선)이 됐다. 자기 오판을 감추면 그 결함은 영영 보고되지 않는다.
+
+**`## 실패 지점`** — 4줄 모두 채운다. 해당 없는 항목은 `없음` + 근거를 쓴다(`프롬프트 이상: 없음 (injection 아님. 훅 차단은 설계대로 동작했으나 대상이 읽기 전용 명령)`). 빈칸으로 두면 "조사하지 않음" 과 구별되지 않는다.
+
+**`## 타임라인`** — 헤딩에 수집 구간을 명시한다. **시각은 KST 표기하고 UTC 를 병기**한다(로그는 UTC 라 병기가 없으면 대조가 안 된다). `**최초 이상 발생**` 행은 굵게 표시해 3.3 의 포착 결과를 한눈에 드러낸다. 마지막에 `> 추정:` 한 덩어리를 둔다.
+
+**`## 에러 메시지`** — 메시지가 둘 이상이면 **번호를 매겨 나눈다**. 항목마다 "무엇의 어디서 나온 메시지인지" 한 줄을 앞에 두고 코드블록을 붙인다. 툴 반환값 JSON 은 요약하지 말고 **필드 전문**을 싣는다 — `next_action` 처럼 에이전트 행동을 지시한 필드가 원인 규명의 핵심인 경우가 있다.
+
+**`## 재현성 / 영향 범위`** — `항상` 이면 무엇이 결정적인지 괄호로 밝힌다(`항상(결정적 — 명령 문자열에 state.json 경로가 포함되면 무조건 차단)`). `간헐적` 이면 관측 횟수를 분수로 쓴다.
+
+**`## 관련 관찰`** (조건부) — 로그에서 같은 증상의 과거 발생을 찾았을 때 넣는다. 표로 시각·에이전트·명령(요약)을 나열하고, **어느 것이 정당한 동작이고 어느 것이 오탐인지 행마다 표시**한다. #5 의 9건 표는 그중 2건을 `(쓰기 측 — 차단 자체는 적절)` 로 구분해, 수정 범위를 정확히 좁혔다.
+
+**`## 참고: 의심 근본 원인 코드`** (조건부) — 설치본(`dist/`)에서 해당 함수·분기를 발췌하고 헤딩에 버전과 파일을 적는다. 왜 의심되는지 불릿으로 덧붙이고, **코드 독해 기반 추정임을 명시**한다. 사내 코드는 여기 넣지 않는다(2.1) — 이 섹션은 makdoong2-team 자체 코드 전용이다.
+
+**`## 부수 관찰 (minor)`** (조건부) — 본 결함과 무관하지만 같은 조사에서 눈에 띈 것. 별도 이슈로 올릴 만큼은 아닌 것만 넣는다. 크면 별도 이슈로 분리한다.
+
+**`## 제안 (참고)`** (조건부) — 번호 매긴 목록. **관측에서 직접 도출되는 것만** 쓴다. 헤딩의 `(참고)` 를 지우지 않는다 — 결정 권한은 유지보수자에게 있다.
+
+**`## 증거`** — 3.4·3.5 를 따른다. `<summary>` 안에는 꺾쇠(`<`, `>`)를 쓰지 않는다(HTML 로 파싱된다). 마지막 고지 2줄은 필수이며, **"토큰·비밀번호·사내 IP 는 포함되지 않음(스캔으로 확인)" 처럼 확인한 사실도 함께 적는다** — 무엇을 안 가렸는지가 아니라 무엇을 확인했는지가 신뢰의 근거다.
+
+### 6.5 기준 사례
+
+[#5](https://github.com/y00njinuk/makdoong2-team/issues/5) 를 참고 원문으로 삼는다. 필요하면 `webfetch` 또는 아래로 원문을 확인한다.
+
+```bash
+curl -sS -H "Accept: application/vnd.github+json" \
+  https://api.github.com/repos/y00njinuk/makdoong2-team/issues/5
+```
+
+다만 **#5 를 복사하지 않는다.** 참고 대상은 구조와 서술 밀도이지 내용이 아니다. 섹션 11–14 의 채택 여부는 이번 조사에서 실제로 나온 근거로 결정한다.
+
+### 6.6 제출 전 자기 점검 (7-1 표시 직전)
+
+payload 를 `cat` 으로 표시하기 **전에** 아래를 전부 통과시킨다. 하나라도 걸리면 본문을 고친 뒤 다시 점검한다(표시 후 수정하면 표시 증명이 무효가 되어 7-1 을 처음부터 다시 해야 한다).
+
+| # | 점검 | 불통과 시 |
+|---|---|---|
+| 1 | 필수 섹션 10개(1–10)와 `## 증거` 가 순서대로 모두 있다 | 빠진 섹션 추가 (`없음`/`미확인` 이라도) |
+| 2 | 제목이 `<어디서> + <무엇이 어떻게> + <그 결과>` 한 문장이고 사내 식별자가 없다 | 6.1 로 재작성 |
+| 3 | `## 타임라인` 에 `**최초 이상 발생**` 행이 있고 KST·UTC 가 병기됐다 | 3.3 포착 결과 반영 |
+| 4 | 모든 코드블록·표 인용에 출처(파일+라인 / 세션+턴)가 붙어 있다 | 출처 추가, 못 달면 삭제 |
+| 5 | 단정과 추정이 구분됐다 — 추정은 전부 `> 추정:` 또는 "추정" 명시 안에 있다 | 단정형 서술을 추정으로 되돌린다 |
+| 6 | 3장에서 나온 근거 중 11–14 에 들어갈 것이 남아 있지 않다 | 해당 섹션 추가 |
+| 7 | 마스킹 자리표시자가 1:1 대응하고, 같은 종류 복수는 접미사로 구분된다 | 자리표시자 재정리 |
+| 8 | 본문 끝 `마스킹 내역` / `마스킹으로 생략된 정보` 2줄이 있다 | 추가 |
+| 9 | 사내 코드·고객 데이터·자격 증명이 어디에도 없다 (2장 grep + 내용 판단) | 해당 블록 제외 |
+| 10 | 본문이 65536자 이내다 | 3.5 방식 2(Gist)로 전환 |
+| 11 | 라벨이 저장소에 실재한다 (기본 `bug` 단독) | 7-2 의 라벨 목록으로 교정 |
+
+점검 결과는 사용자에게 별도로 보고하지 않는다. 7-1 에서 표시하는 원문이 곧 결과다.
+
 ---
 
 ## 7. 이슈 생성
@@ -428,7 +570,7 @@ curl -sS -X POST https://api.github.com/repos/y00njinuk/makdoong2-team/issues/<n
 
 GitHub 쓰기 호출(이슈·코멘트·Gist·라벨 생성)은 다음 절차를 거쳐야만 훅을 통과한다:
 
-1. payload 를 **리터럴 절대 경로** 파일로 작성한다 (예: `/tmp/makdoong2-issue/issue-payload.json`). 상대 경로·변수 포함 경로는 훅이 거부한다.
+1. **본문을 6장 양식으로 작성하고 6.6 자기 점검을 통과시킨 뒤**, payload 를 **리터럴 절대 경로** 파일로 작성한다 (예: `/tmp/makdoong2-issue/issue-payload.json`). 상대 경로·변수 포함 경로는 훅이 거부한다. 점검을 표시 이후로 미루지 않는다 — 표시 후 본문을 고치면 표시 증명이 무효가 되어 2번부터 다시 해야 한다.
 2. **게시될 원문 전체를 세션에 그대로 표시한다** — 제목, 라벨, 본문 전문. 요약·발췌로 대체하지 않는다. 표시는 **체이닝 없는 단독 `cat`** 이어야 한다:
    ```bash
    cat /tmp/makdoong2-issue/issue-payload.json

package/stages/02-requirements.md

@@ -280,7 +280,7 @@ major 로 판정되어도 `auto_approve` 맵은 **모두 true** 로 두고 `"cat
 
 ## 2-5. 최종 자가 검증 (Pre-Completion Checklist)
 
-`done=true` 직전, 다음 6항목을 자체 확인하고 state.json에 결과를 기록한다.
+`done=true` 직전, 다음 9항목을 자체 확인하고 state.json에 결과를 기록한다.
 하나라도 false면 완료 기록 금지.
 
 | 항목 | 확인 |
@@ -293,10 +293,18 @@ major 로 판정되어도 `auto_approve` 맵은 **모두 true** 로 두고 `"cat
 | 6 | 작업 범주화(2-4b)가 끝나 `.policy.category`(minor\|major)와 `auto_approve` 맵이 기록되었다 |
 | 7 | `ambiguity_score`가 산정·기록되었고 최종값 ≤ 0.2 이다 (2-3-2b) |
 | 8 | 확정 명세가 동결되어 `spec_hash`가 기록되었다 (2-4a) |
+| 9 | `draft_path` 마커가 state.json에 기록되었다 (2-0). **`spec_hash`와 한 쌍이다** — `stage3-scope-verify.sh`가 `spec_hash`만 있고 `draft_path`가 없으면 `1_planning.scope` 진입을 하드 차단한다 |
+
+**9번은 자기선언이 아니라 실제 값을 읽어 확인한다** — `draft_synced`(파일 동기화)가 true 여도 마커는 빠질 수 있다. 실제로 `spec_hash`만 기록되고 `draft_path`가 누락된 채 8항목 전부 true 로 종료되어, 다음 게이트에서 워크플로우가 정지한 사례가 있다 (issue #6-①).
+
+```bash
+bash <SCRIPTS_DIR>/state.sh get <이슈키> '.stages."1_planning".substages."requirements".draft_path'
+# → "null" 이면 2-0 의 set 명령으로 먼저 기록한 뒤 self_check 을 기록한다.
+```
 
 ```bash
 bash <SCRIPTS_DIR>/state.sh set <이슈키> '.stages."1_planning".substages."requirements".self_check' \
-  '{"checklist_complete": true, "conflicts_resolved": true, "user_confirmed": true, "scope_clean": true, "draft_synced": true, "categorized": true, "ambiguity_converged": true, "spec_frozen": true}'
+  '{"checklist_complete": true, "conflicts_resolved": true, "user_confirmed": true, "scope_clean": true, "draft_synced": true, "categorized": true, "ambiguity_converged": true, "spec_frozen": true, "draft_recorded": true}'
 ```
 
 ## 완료 기록