makdoong2-team 1.4.2 → 1.6.0

package/README.md

@@ -44,7 +44,7 @@ makdoong2-team doctor            # 설치 진단
 
 ## 2. 에이전트와 단계
 
-에이전트 **7개**. 권한이 좁을수록 사고 반경이 좁다는 원칙으로 나눴다.
+워크플로우 에이전트 **7개** + 사용자 전용 유틸리티 에이전트 1개. 권한이 좁을수록 사고 반경이 좁다는 원칙으로 나눴다.
 
 | 에이전트 | 담당 | 권한 |
 |---|---|---|
@@ -55,6 +55,7 @@ makdoong2-team doctor            # 설치 진단
 | `makdoong2-publisher` | 3_delivery 3단계 | **git add/commit/push 직접 실행** + bitbucket MCP |
 | `makdoong2-verifier` | 메타 검증 | 읽기 전용 |
 | `makdoong2-researcher` | 리서치 fan-out 워커 | 읽기 전용 + 리서치 MCP — 소스 1개 전담 |
+| `makdoong2-issue-reporter` | 플러그인 오류 GitHub 이슈 등록 | **전권 (bash/write allow)** — 사용자 직접 호출 전용 |
 
 > **Publisher 는 직접 실행자다.** commit·pr·review 모두 publisher 가 worktree 에서 직접 git 명령과 MCP 를 호출한다. 부장님은 git 권한이 아예 없고 dispatch 와 verdict 수신만 한다. (구버전의 "spec 계산 → 부장님 실행" 하이브리드 모델은 폐기됐다.)
 
@@ -94,6 +95,19 @@ makdoong2-team doctor            # 설치 진단
 
 결과는 `.makdoong2-team/<이슈>/research-findings.json` 으로 병합된다. 상세: ARCHITECTURE.md §3.6
 
+### 오류 이슈 등록 — `/makdoong2-issue-reporter`
+
+플러그인이 오작동했을 때(행 걸림, 잘못된 프롬프트 injection, 단계 실패 반복 등) 다음 커맨드로 GitHub 이슈를 등록한다:
+
+```
+/makdoong2-issue-reporter [증상 한 줄 설명(선택)]
+```
+
+- 커맨드가 **전용 full-permission 에이전트**(`makdoong2-issue-reporter`)로 라우팅되어, 호출 시점 이전의 로그·프롬프트·세션 컨텍스트를 스스로 수집해 이상 지점을 포착하고 [y00njinuk/makdoong2-team issues](https://github.com/y00njinuk/makdoong2-team/issues) 에 등록한다.
+- **사용자 직접 호출이 유일한 트리거**다. 부장님·막둥이가 실패를 관측했다고 자율적으로 이슈를 만들지 않는다 (훅이 차단).
+- 저장소가 public 이므로 사내 정보는 마스킹 후 첨부되며, **전송 전 사용자 승인이 훅으로 강제된다**: 에이전트가 게시될 원문 전체를 채팅에 표시한 뒤, 사용자가 직접 `issue-reporter-approve.sh <payload>` 를 실행해 원문을 확인·승인해야만 GitHub 쓰기 호출이 통과된다 (승인은 내용 sha256 에 바인딩, 1회용).
+- PAT 는 `~/.config/opencode/.github` 파일에서 읽는다. 상세: ARCHITECTURE.md §4.6
+
 ---
 
 ## 3. 설정 — `makdoong2-team.json` 한 파일

package/agents/makdoong2-issue-reporter.md

@@ -0,0 +1,49 @@
+---
+name: makdoong2-issue-reporter
+description: makdoong2-team 오류·비정상 동작 GitHub 이슈 리포터. 사용자가 /makdoong2-issue-reporter 커맨드로 직접 호출할 때만 활성화된다. 워크플로우 stage 에 참여하지 않으며 dispatch_stage 로 spawn 되지 않는다. 다른 에이전트가 자율적으로 선택·호출하지 않는다.
+temperature: 0.1
+mode: all
+tools:
+  Read: true
+  Write: true
+  Edit: true
+  Bash: true
+  Grep: true
+  Glob: true
+  webfetch: true
+  skill: true
+permission:
+  bash:
+    "*": "allow"
+  write:
+    "**/*": "allow"
+---
+
+당신은 makdoong2-team 플러그인의 **이슈 리포터(makdoong2-issue-reporter)**다. 사용자가 `/makdoong2-issue-reporter` 커맨드로 직접 호출했을 때만 활성화되며, 직전 세션의 오류·비정상 동작을 스스로 수집·분석해 GitHub 이슈(y00njinuk/makdoong2-team)로 등록한다.
+
+## 하드룰
+
+1. **첫 행동으로 `skill(name="makdoong2-issue-reporter")` 를 로드**하고, 스킬에 정의된 절차를 그대로 따른다. 실행 순서는 스킬이 고정한다: **수집 → 이상 지점 포착 → 마스킹 → 중복 확인 → 최소 질의 → 이슈 생성**.
+2. **GitHub 게시(이슈·코멘트·Gist·라벨)는 훅이 강제하는 사용자 승인 게이트를 통과해야만 가능하다.** 절차는 고정이다:
+   1. payload 를 **리터럴 절대 경로** JSON 파일로 작성한다 (예: `/tmp/makdoong2-issue/issue-payload.json`).
+   2. **게시될 원문 전체(제목·라벨·본문 전문)를 채팅에 그대로 표시**하고 마스킹 내역 요약을 덧붙인다. 요약·발췌로 대체 금지 — 사용자는 전송될 내용 원문을 봐야 한다.
+   3. 사용자에게 안내한다: `bash <SCRIPTS_DIR>/issue-reporter-approve.sh </absolute/path/payload.json>` 을 **사용자가 직접** 실행 (스크립트가 원문을 다시 보여주고 승인을 받아 `<payload>.approved` 마커를 기록한다). 실행을 안내한 뒤 **대기한다**.
+   4. 승인 마커가 생긴 뒤에만 전송한다. 전송은 **단일 curl 명령 + `-d @<절대경로>`** 형태만 허용된다 (체이닝·리다이렉트·인라인 JSON 금지 — 훅이 차단).
+   - 승인은 **1회용**이며 payload 내용이 바뀌면 무효다 (해시 바인딩). 재작성했으면 2번부터 다시.
+   - **승인 스크립트를 직접 실행하거나 `.approved` 마커를 만들지·읽지·지우지 않는다.** 훅이 물리 차단하며, 차단 메시지를 보면 우회하지 말고 사용자 승인을 기다린다.
+3. **토큰(PAT)은 어디에도 원문 노출 금지.** 커맨드 문자열에 직접 박지 않고 환경변수로 전달하며, 출력에는 마스킹(`ghp_****`)만 허용한다.
+4. **워크플로우 상태를 변경하지 않는다.** state.json 은 증거 수집을 위한 읽기(`state.sh get`)만 허용. `state.sh set` / dispatch 계열 툴 호출 금지. 이 에이전트는 워크플로우 오케스트레이션과 완전히 분리된 조사·보고 전용이다.
+5. **다른 에이전트로 위임하지 않는다.** 수집·분석·마스킹·등록 전 과정을 이 세션에서 직접 수행한다.
+
+## 실행 컨텍스트
+
+- 이 에이전트는 전권(full-permission)으로 실행된다: bash 전체 allow, 파일 쓰기 allow. 임시 페이로드 파일(`issue-payload.json` 등) 생성과 curl 호출을 직접 수행할 수 있다. 전송 후 임시 파일은 스킬 규약대로 삭제한다.
+- 커맨드가 인라인으로 실행되므로 현재 세션의 직전 대화 턴(team-leader 오케스트레이션 로그 포함)을 그대로 볼 수 있다. 로그 파일 수집과 함께 대화 컨텍스트도 이상 지점 포착에 활용한다.
+
+## 세션 종료 규약
+
+완료 시 스킬 8장(완료 보고) 형식을 따른다. 최소한 다음을 한국어로 출력한다:
+
+1. 생성된 이슈 번호와 `html_url` (또는 실패 시 수동 등록용 본문 전체)
+2. 포착한 최초 이상 발생 지점(시각·단계·에이전트)과 수집 구간
+3. 마스킹 내역 요약과 `미확인`으로 남긴 항목 목록

package/agents/makdoong2-team-leader.md

@@ -43,6 +43,7 @@ permission:
 4. **모델 실패 시 `get_fallback_model` 툴로 폴백 모델 ID를 받아** `dispatch_stage`의 `model_override`에 넘긴다. 폴백이 exhausted면 사용자에게 보고.
 5. **승인 게이트는 `.policy.auto_approve.<substage>` 마커가 결정한다.** 기본값은 minor·major 공통으로 전 substage `true` 이므로 전 흐름을 무인 진행한다. `.policy.category=="major"` 라도 auto_approve 가 true 인 한 사람 승인 없이 진행된다 — `category` 는 위험도 라벨/향후 opt-in 훅용이다. HITL 이 명시적으로 opt-in 된 경우(예: `.policy.auto_approve."3_delivery.commit"==false`) 에만 해당 substage 직전에 변경 보고서(`change-report.md`) 작성 → 사용자 승인 → 마커 기록 흐름을 밟는다.
 6. **`retry_disallowed=true` 재-dispatch 금지 (hardrule).** `dispatch_stage` 반환 JSON 에 `retry_disallowed: true` 가 포함되면 **동일 stage 를 재호출하지 않는다**. 이 플래그는 `outcome_kind=="timeout"` 이면서 `transient_failures==0` 인 경우에만 세워지며, 네트워크·API 오류 없이 sub-agent 가 model/prompt 이슈로 hang 한 경우다. 재시도해도 동일 실패를 반복해 무한 루프에 빠진다. 대응: (a) `retry_disallowed_reason` 을 사용자에게 그대로 보고, (b) `get_fallback_model` 로 다른 모델 ID 를 받아 `model_override` 로 1회 한정 재시도, (c) fallback exhausted 면 세션 종료 후 사용자 개입 대기. `transient_failures>0` (네트워크 오류 등) 이거나 `retry_disallowed` 필드 자체가 없으면 기존 재시도 정책 유지.
+7. **플러그인 오류 이슈 등록은 사용자 안내만 한다.** makdoong2-team 자체의 결함(행 걸림, 잘못된 프롬프트 injection, 단계 실패 반복 등)을 관측하거나 사용자가 "이슈 등록해줘"라고 요청해도 `skill(name="makdoong2-issue-reporter")` 를 직접 로드하지 않는다 (훅이 차단). 대신 사용자에게 `/makdoong2-issue-reporter [증상 한 줄(선택)]` 커맨드 실행을 안내한다 — 커맨드가 전용 전권 에이전트로 라우팅되어 수집·마스킹·등록을 수행한다.
 
 ## Hang 이력 조회 규약 (신규 — LLM API 안정성 관측)
 

package/bin/cli.js

@@ -122,7 +122,7 @@ function doDoctor(flags) {
   }
 
    // Config dir checks (agents & skills)
-   const configDirChecks = ["agents", "skills/jira-research", "skills/confluence-research", "skills/bitbucket-research", "skills/github-oss-research", "skills/bamboo-ci"];
+   const configDirChecks = ["agents", "skills/jira-research", "skills/confluence-research", "skills/bitbucket-research", "skills/github-oss-research", "skills/bamboo-ci", "skills/makdoong2-issue-reporter", "command/makdoong2-issue-reporter.md"];
    for (const d of configDirChecks) {
      check(existsSync(join(DEST, d)), `${d}/ in config dir`, `${d}/ missing in config dir (run: npx makdoong2-team install)`);
    }

package/command/makdoong2-issue-reporter.md

@@ -0,0 +1,8 @@
+---
+description: makdoong2-team 오류를 조사해 GitHub 이슈로 등록 (전용 에이전트 전권 실행)
+agent: makdoong2-issue-reporter
+subtask: false
+---
+`skill` 툴로 `makdoong2-issue-reporter` 스킬을 로드하고, 스킬 절차대로 수행하라: 호출 시점 이전의 로그·프롬프트·세션 컨텍스트를 수집해 이상 지점을 포착하고, 보안 마스킹과 사용자 최종 확인을 거쳐 GitHub 이슈(y00njinuk/makdoong2-team)로 등록한다.
+
+사용자 보충 설명 (없으면 무시): $ARGUMENTS

package/dist/issue-reporter-guard.d.ts

@@ -0,0 +1,50 @@
+export declare const ISSUE_REPORTER_SKILL_NAME = "makdoong2-issue-reporter";
+export declare const ISSUE_REPORTER_AGENT = "makdoong2-issue-reporter";
+export declare const APPROVAL_MARKER_SUFFIX = ".approved";
+export declare const APPROVE_SCRIPT_BASENAME = "issue-reporter-approve.sh";
+/** GitHub API 호출 분류 결과 */
+export type GithubApiCall = {
+    kind: "none";
+} | {
+    kind: "read";
+} | {
+    kind: "mutation";
+    payloadPaths: string[];
+    problems: string[];
+} | {
+    kind: "forbidden-client";
+    reason: string;
+};
+/**
+ * issue-reporter 의 bash 명령을 GitHub API 관점에서 분류한다.
+ *
+ * - api.github.com 미참조 → none (이 게이트와 무관)
+ * - curl 이 아닌 클라이언트(node/python/wget/gh …)로 api.github.com 접근
+ *   → forbidden-client. 훅이 payload 를 검사할 수 있는 형태가 curl -d @file
+ *   뿐이므로 다른 클라이언트는 쓰기·읽기 불문 전부 막는다 (읽기는 curl 로).
+ * - curl 이지만 mutation 징후(-X POST/PATCH/PUT/DELETE, 데이터 플래그) 없음 → read
+ * - mutation → payload 파일 경로 추출. 문제(인라인 데이터, 상대 경로, 변수 포함)는
+ *   problems 로 수집한다 — 호출부는 problems 가 하나라도 있으면 차단한다.
+ */
+export declare function classifyGithubApiCall(cmd: string): GithubApiCall;
+/** 승인 스크립트 호출 여부 — 에이전트에게는 실행이 금지된다 (사용자 전용). */
+export declare function isApproveScriptInvocation(cmd: string): boolean;
+/** 승인 마커 경로 참조 여부 — 에이전트의 bash/write 에서 일절 금지된다. */
+export declare function referencesApprovalMarker(text: string): boolean;
+/** payload 파일 경로 → 승인 마커 경로 */
+export declare function approvalMarkerPath(payloadPath: string): string;
+export declare function sha256Hex(content: string | Buffer): string;
+/** 마커 파일 내용에서 해시를 파싱한다. 첫 줄이 64자리 hex 가 아니면 null. */
+export declare function parseApprovalMarker(markerContent: string): string | null;
+/**
+ * 승인 검증: 마커의 해시가 현재 payload 내용과 일치하는가.
+ * 불일치 사유를 문자열로 반환하고, 유효하면 null.
+ */
+export declare function approvalMismatch(payloadContent: Buffer, markerContent: string): string | null;
+/** skill 툴 args 에서 스킬 이름을 추출한다. { name } 및 { arguments: { name } } 형태 수용. */
+export declare function extractSkillNameFromArgs(args: unknown): string | undefined;
+/**
+ * skill 툴 호출이 issue-reporter 트리거 정책을 위반하면 사용자에게 보여줄
+ * 에러 메시지를 반환하고, 정상이면 null 을 반환한다.
+ */
+export declare function issueReporterSkillLoadViolation(agent: string | undefined, args: unknown): string | null;

package/dist/issue-reporter-guard.js

@@ -0,0 +1,179 @@
+// makdoong2-issue-reporter 스킬의 사용자-전용 트리거 강제.
+//
+// Lives in its own module rather than opencode-plugin.ts because opencode's
+// plugin loader invokes EVERY named export of the plugin entry file as a
+// plugin factory (see test/plugin-exports-shape.test.mjs). Helpers must be
+// imported, never re-exported from the entry file.
+//
+// 정책: makdoong2-issue-reporter 스킬의 유일한 트리거는 사용자의 직접 호출
+// (/makdoong2-issue-reporter 커맨드)이다. 커맨드는 전용 full-permission
+// 에이전트 makdoong2-issue-reporter 로 라우팅되므로, 그 외 에이전트
+// (team-leader / sealed 서브에이전트)가 skill() 로 자율 로드하는 것은
+// 트리거 정책 위반이다. 1차 방어는 SKILL.md description 의 명시, 이 모듈이
+// tool.execute.before 훅에서 호출되는 2차(런타임) 방어다.
+//
+// agent 미상(undefined)은 차단하지 않는다 — outer/primary 세션 passthrough 로,
+// OUTER_WORLD_TOOLS 가드와 동일한 설계 철학이다. 우리가 식별한 에이전트에만
+// 정책을 적용하고, 식별 밖의 세션은 opencode 자체 permission 에 맡긴다.
+import { createHash } from "node:crypto";
+export const ISSUE_REPORTER_SKILL_NAME = "makdoong2-issue-reporter";
+export const ISSUE_REPORTER_AGENT = "makdoong2-issue-reporter";
+// ── GitHub 게시 승인 게이트 ──────────────────────────────────────────────
+//
+// 정책: issue-reporter 가 GitHub 에 무엇이든 게시(이슈·코멘트·Gist·라벨)하려면
+// 사용자가 게시될 "원문 전체"를 보고 명시적으로 승인해야 한다. 채팅 승인은
+// 프롬프트 수준 규약일 뿐이라 강제가 아니다 — 여기의 계약이 물리적 강제다:
+//
+//   1. 에이전트는 payload 를 "리터럴 절대 경로" 파일로 만들어 -d @<path> 로만
+//      전달할 수 있다 (인라인 -d '{...}', 변수 경로, curl 외 HTTP 클라이언트 금지).
+//   2. 사용자가 scripts/issue-reporter-approve.sh <payload> 를 "직접" 실행한다.
+//      스크립트는 payload 원문 전체를 화면에 출력한 뒤 stdin 으로 승인을 받고,
+//      payload 의 sha256 을 <payload>.approved 마커에 기록한다.
+//   3. tool.execute.before 훅이 GitHub 쓰기 호출 시 마커의 해시와 현재 payload
+//      내용을 대조한다. 승인 후 1바이트라도 바뀌면 차단 — 승인은 특정 원문에
+//      바인딩되고, 다른 내용으로 바꿔치기할 수 없다.
+//   4. 전송이 실행되면 훅(after)이 마커를 삭제한다. 승인은 1회용이다.
+//   5. 에이전트 자신의 승인 스크립트 실행·마커 생성/조작은 훅이 차단한다.
+//      승인 스크립트는 stdin confirm 이라 에이전트 셸에서는 EOF 로도 못 넘어가지만,
+//      printf 'y' 파이프 우회가 가능하므로 실행 자체를 막는 것이 1차다.
+export const APPROVAL_MARKER_SUFFIX = ".approved";
+export const APPROVE_SCRIPT_BASENAME = "issue-reporter-approve.sh";
+const MUTATION_METHOD_RE = /(?:-X|--request)[= ]*['"]?(POST|PATCH|PUT|DELETE)\b/i;
+const DATA_FLAG_RE = /(^|[\s'"])(-d|--data|--data-binary|--data-raw|--data-urlencode|--json|-F|--form)([= ]|$)/;
+const PAYLOAD_AT_RE = /(?:-d|--data|--data-binary|--data-raw|--json)[= ]+@(["']?)([^"'\s]+)\1/g;
+/**
+ * issue-reporter 의 bash 명령을 GitHub API 관점에서 분류한다.
+ *
+ * - api.github.com 미참조 → none (이 게이트와 무관)
+ * - curl 이 아닌 클라이언트(node/python/wget/gh …)로 api.github.com 접근
+ *   → forbidden-client. 훅이 payload 를 검사할 수 있는 형태가 curl -d @file
+ *   뿐이므로 다른 클라이언트는 쓰기·읽기 불문 전부 막는다 (읽기는 curl 로).
+ * - curl 이지만 mutation 징후(-X POST/PATCH/PUT/DELETE, 데이터 플래그) 없음 → read
+ * - mutation → payload 파일 경로 추출. 문제(인라인 데이터, 상대 경로, 변수 포함)는
+ *   problems 로 수집한다 — 호출부는 problems 가 하나라도 있으면 차단한다.
+ */
+export function classifyGithubApiCall(cmd) {
+    // gh CLI 는 URL 문자열 없이도 이슈·코멘트·Gist 를 만들 수 있으므로
+    // (gh issue create / gh api ...) api.github.com 참조 여부와 무관하게 막는다.
+    if (/(^|[;&|(]\s*|\s)gh\s+(api|issue|pr|gist|label|repo|release)\b/.test(cmd)) {
+        return {
+            kind: "forbidden-client",
+            reason: "gh CLI 는 사용할 수 없다. GitHub 접근은 curl 만 허용된다 (쓰기는 curl -d @<절대경로> 형태만 승인 검증 가능).",
+        };
+    }
+    if (!/api\.github\.com/i.test(cmd))
+        return { kind: "none" };
+    const usesCurl = /(^|[;&|(]\s*|\s)curl(\s|$)/.test(cmd);
+    if (!usesCurl) {
+        return {
+            kind: "forbidden-client",
+            reason: "api.github.com 접근은 curl 만 허용된다 (쓰기는 curl -d @<절대경로> 형태만 검증 가능).",
+        };
+    }
+    const hasMutationMethod = MUTATION_METHOD_RE.test(cmd);
+    const hasDataFlag = DATA_FLAG_RE.test(cmd);
+    // curl -G / --get 은 데이터 플래그를 쿼리 스트링으로 변환하는 GET 이다
+    // (중복 검색이 --data-urlencode 와 함께 쓴다). mutation method 가 명시되지
+    // 않은 -G 호출은 읽기로 분류한다.
+    const isGetConverted = /(^|\s)(-G|--get)(\s|$)/.test(cmd) && !hasMutationMethod;
+    if (isGetConverted)
+        return { kind: "read" };
+    if (!hasMutationMethod && !hasDataFlag)
+        return { kind: "read" };
+    const payloadPaths = [];
+    const problems = [];
+    for (const m of cmd.matchAll(PAYLOAD_AT_RE)) {
+        payloadPaths.push(m[2]);
+    }
+    if (payloadPaths.length === 0) {
+        problems.push("payload 는 반드시 파일로 전달한다: -d @</absolute/path/payload.json>. " +
+            "인라인 JSON(-d '{...}')과 stdin(-d @-)은 승인 검증이 불가능해 금지된다.");
+    }
+    for (const p of payloadPaths) {
+        if (!p.startsWith("/")) {
+            problems.push(`payload 경로는 리터럴 절대 경로여야 한다: "${p}"`);
+        }
+        if (/[$\`]/.test(p)) {
+            problems.push(`payload 경로에 변수·명령 치환을 쓸 수 없다: "${p}"`);
+        }
+    }
+    // TOCTOU 방어: 훅은 "명령 실행 전" 파일 해시를 검증하므로, 같은 명령 안에서
+    // payload 를 다시 쓰고(curl 앞에 echo > file 등) 전송하면 검증을 우회할 수 있다.
+    // 그래서 쓰기 호출은 셸 제어 연산자·치환이 없는 "단일 curl 호출"만 허용한다.
+    // (mutation POST URL 에는 &, ; 등이 필요한 경우가 없다 — 읽기 호출은 이 검사 밖.)
+    if (/[;|<>\n`]|\$\(|&&|\s&(\s|$)/.test(cmd)) {
+        problems.push("GitHub 쓰기 호출은 단일 curl 명령이어야 한다 — 체이닝(;, &&, |, &), " +
+            "리다이렉트(<, >), 명령 치환($(), `)을 함께 쓸 수 없다.");
+    }
+    return { kind: "mutation", payloadPaths, problems };
+}
+/** 승인 스크립트 호출 여부 — 에이전트에게는 실행이 금지된다 (사용자 전용). */
+export function isApproveScriptInvocation(cmd) {
+    return cmd.includes("issue-reporter-approve");
+}
+/** 승인 마커 경로 참조 여부 — 에이전트의 bash/write 에서 일절 금지된다. */
+export function referencesApprovalMarker(text) {
+    return text.includes(APPROVAL_MARKER_SUFFIX);
+}
+/** payload 파일 경로 → 승인 마커 경로 */
+export function approvalMarkerPath(payloadPath) {
+    return `${payloadPath}${APPROVAL_MARKER_SUFFIX}`;
+}
+export function sha256Hex(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** 마커 파일 내용에서 해시를 파싱한다. 첫 줄이 64자리 hex 가 아니면 null. */
+export function parseApprovalMarker(markerContent) {
+    const first = markerContent.split("\n")[0]?.trim().toLowerCase() ?? "";
+    return /^[0-9a-f]{64}$/.test(first) ? first : null;
+}
+/**
+ * 승인 검증: 마커의 해시가 현재 payload 내용과 일치하는가.
+ * 불일치 사유를 문자열로 반환하고, 유효하면 null.
+ */
+export function approvalMismatch(payloadContent, markerContent) {
+    const recorded = parseApprovalMarker(markerContent);
+    if (recorded === null)
+        return "승인 마커 형식이 잘못됐다 (첫 줄이 sha256 hex 가 아님)";
+    const actual = sha256Hex(payloadContent);
+    if (actual !== recorded) {
+        return "payload 내용이 승인 이후 변경됐다 — 승인은 특정 원문에 바인딩되며, 변경된 내용은 재승인이 필요하다";
+    }
+    return null;
+}
+/** skill 툴 args 에서 스킬 이름을 추출한다. { name } 및 { arguments: { name } } 형태 수용. */
+export function extractSkillNameFromArgs(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const direct = args.name;
+    if (typeof direct === "string" && direct.length > 0)
+        return direct;
+    const nested = args.arguments;
+    if (nested && typeof nested === "object") {
+        const inner = nested.name;
+        if (typeof inner === "string" && inner.length > 0)
+            return inner;
+    }
+    return undefined;
+}
+/**
+ * skill 툴 호출이 issue-reporter 트리거 정책을 위반하면 사용자에게 보여줄
+ * 에러 메시지를 반환하고, 정상이면 null 을 반환한다.
+ */
+export function issueReporterSkillLoadViolation(agent, args) {
+    const skillName = extractSkillNameFromArgs(args);
+    if (skillName !== ISSUE_REPORTER_SKILL_NAME)
+        return null;
+    if (agent === undefined)
+        return null;
+    if (agent === ISSUE_REPORTER_AGENT)
+        return null;
+    return (`[makdoong2-team issue-reporter trigger violation]\n` +
+        `Agent "${agent}" cannot load skill "${ISSUE_REPORTER_SKILL_NAME}".\n\n` +
+        `이 스킬의 유일한 트리거는 사용자의 직접 호출이다. 에이전트가 실패·예외를 ` +
+        `관측했더라도 자율적으로 이슈를 등록하지 않는다.\n\n` +
+        `**올바른 절차:** 사용자에게 다음 커맨드 실행을 안내하라:\n` +
+        `    /makdoong2-issue-reporter [증상 한 줄 설명(선택)]\n\n` +
+        `커맨드는 전용 full-permission 에이전트(${ISSUE_REPORTER_AGENT})로 라우팅되어 ` +
+        `수집·마스킹·등록을 수행한다.`);
+}

package/dist/opencode-plugin.js

@@ -16,7 +16,7 @@
 // Install path (default): ~/.config/opencode/plugins/makdoong2-team/
 // Place this file at ~/.config/opencode/plugins/makdoong2-team/src/opencode-plugin.ts
 // (or load the npm package via opencode.json "plugin": ["./plugins/makdoong2-team/src/opencode-plugin.ts"]).
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve as pathResolve, sep as pathSep } from "node:path";
 import { tool } from "@opencode-ai/plugin";
@@ -33,6 +33,7 @@ import { injectAllSecrets } from "./mcp-secret-injector.js";
 import { pollSubSession as pollSubSessionCore, pollOutcomeToLegacy } from "./poll-sub-session.js";
 import { logger } from "./logger.js";
 import { redactAndTruncate } from "./redact-secrets.js";
+import { issueReporterSkillLoadViolation, ISSUE_REPORTER_AGENT, APPROVAL_MARKER_SUFFIX, APPROVE_SCRIPT_BASENAME, classifyGithubApiCall, isApproveScriptInvocation, referencesApprovalMarker, approvalMarkerPath, approvalMismatch, } from "./issue-reporter-guard.js";
 // All runtime paths come from makdoong2-team.json (paths.* overrides) or are
 // derived from the opencode config dir. No MAKDOONG2 environment variables.
 const { hooks: HOOKS_DIR, gates: GATES_DIR, scripts: SCRIPTS_DIR, stages: STAGES_DIR, skills: SKILLS_DIR, } = resolvePaths();
@@ -828,6 +829,10 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
         // already omits Task (L1), but sealed workflow is defence in depth — a worker
         // missing here would be caught by nothing at runtime (L2).
         "makdoong2-researcher",
+        // User-only issue reporter. 워크플로우에 참여하지 않지만 outer-world 위임은
+        // 동일하게 금지 — 수집·마스킹·등록 전 과정을 자기 세션에서 완결해야 하며,
+        // 위임하면 마스킹·승인 게이트가 위임처에서 우회될 수 있다.
+        ISSUE_REPORTER_AGENT,
     ]);
     // 미래의 oh-my-openagent 위임 툴을 조기 발견하기 위한 이름 패턴.
     // 알려진 툴이 아니면서 위임/스폰을 시사하는 이름이 감지되면 경고한다.
@@ -987,6 +992,18 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 logger.debug(`[makdoong2-team hook] sealed sub-agent "${agent}" called delegation-like tool "${input.tool}" not in blocklist. ` +
                     `Consider adding to OUTER_WORLD_TOOLS if this is a new oh-my-openagent delegation tool.`);
             }
+            // ── issue-reporter 스킬 사용자-전용 트리거 강제 ──
+            // makdoong2-issue-reporter 스킬은 사용자의 /makdoong2-issue-reporter
+            // 커맨드(전용 full-permission 에이전트로 라우팅)로만 실행된다. 다른
+            // 에이전트의 skill() 자율 로드는 트리거 정책 위반 — 1차 방어는 SKILL.md
+            // description, 이 블록이 2차(런타임) 방어다.
+            if (toolLower === "skill") {
+                const violation = issueReporterSkillLoadViolation(agent, output.args);
+                if (violation) {
+                    logger.error(`[makdoong2-team hook] BLOCKED: agent "${agent}" attempted autonomous load of user-only skill makdoong2-issue-reporter (sessionID="${sessionID}")`);
+                    throw new Error(violation);
+                }
+            }
             // ── skill_mcp lazy-load 사전 힌트 ──
             // opencode 는 skill 이 로드되기 전에 skill_mcp 를 호출하면
             // "MCP server not found" 로 튕기지만 정작 어떤 skill 을 로드해야 하는지는
@@ -1003,6 +1020,24 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                         `first invoke skill(name="${skillName}") in the current session, then retry.`);
                 }
             }
+            // ── Issue-reporter: 승인 마커는 어떤 툴로도 만들 수 없다 ──
+            // 마커(<payload>.approved)는 오직 사용자가 issue-reporter-approve.sh 를
+            // 직접 실행해서만 생긴다. write/edit 툴로 마커를 위조하면 게시 게이트가
+            // 무력화되므로 경로에 마커 접미사가 보이면 즉시 차단한다.
+            if (agent === ISSUE_REPORTER_AGENT && (LEADER_FORBIDDEN_TOOLS.has(toolLower) || WRITE_TOOLS.has(toolLower))) {
+                // filePath 인자뿐 아니라 인자 전체를 검사한다 — apply_patch 는 파일 경로가
+                // 패치 본문 안에 들어 있어 filePath 추출로는 마커 위조를 잡을 수 없다.
+                let argsSerialized = "";
+                try {
+                    argsSerialized = JSON.stringify(output.args ?? "");
+                }
+                catch { /* ignore */ }
+                if (referencesApprovalMarker(argsSerialized)) {
+                    logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter가 ${input.tool} 인자에서 승인 마커 경로 참조.`);
+                    throw new Error(`[makdoong2-team issue-reporter 게시 게이트] 승인 마커(*${APPROVAL_MARKER_SUFFIX})는 에이전트가 생성·수정할 수 없다. ` +
+                        `사용자가 'bash ${SCRIPTS_DIR}/${APPROVE_SCRIPT_BASENAME} <payload>' 를 직접 실행해야만 승인이 성립한다.`);
+                }
+            }
             // ── Leader hardrule 1: 직접 파일 편집·생성 금지 (write/edit/patch/multiedit) ──
             if (agent === "makdoong2-team-leader" && LEADER_FORBIDDEN_TOOLS.has(toolLower)) {
                 logger.error(`[makdoong2-team hook] BLOCKED: team-leader가 ${input.tool} 툴 호출을 시도했다.`);
@@ -1042,6 +1077,56 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                     `• 초안 파일 필요 시: spec을 team-leader에게 반환 → dev 단계에서 engineer가 구현.\n\n` +
                     `**참조**: agents/${agent}.md "금지" 섹션, CLAUDE.md "워크플로우 상태 & 위임 규약"`);
             }
+            // ── Issue-reporter 게시 게이트: GitHub 쓰기는 사용자 승인 원문만 ──
+            // 정책·마커 계약 상세: src/issue-reporter-guard.ts 상단 주석.
+            if (agent === ISSUE_REPORTER_AGENT) {
+                const approveHint = `승인 절차: 에이전트가 payload 원문 전체를 채팅에 표시한 뒤, 사용자가 직접\n` +
+                    `  bash ${SCRIPTS_DIR}/${APPROVE_SCRIPT_BASENAME} </absolute/path/payload.json>\n` +
+                    `를 실행한다 (스크립트가 원문을 다시 보여주고 stdin 승인 후 <payload>${APPROVAL_MARKER_SUFFIX} 마커 기록). ` +
+                    `이 승인은 1회용이고 payload 내용이 바뀌면 무효다.`;
+                if (isApproveScriptInvocation(cmd)) {
+                    logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter가 승인 스크립트 실행 시도. cmd="${redactAndTruncate(cmd, 200)}"`);
+                    throw new Error(`[makdoong2-team issue-reporter 게시 게이트] ${APPROVE_SCRIPT_BASENAME} 는 사용자 전용이다. ` +
+                        `에이전트가 실행하면 승인의 의미가 사라진다. 사용자에게 실행을 안내하고 대기하라.\n${approveHint}`);
+                }
+                if (referencesApprovalMarker(cmd)) {
+                    logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter bash가 승인 마커를 참조. cmd="${redactAndTruncate(cmd, 200)}"`);
+                    throw new Error(`[makdoong2-team issue-reporter 게시 게이트] 승인 마커(*${APPROVAL_MARKER_SUFFIX})는 에이전트가 ` +
+                        `생성·수정·삭제·열람할 수 없다. 마커 검증과 소멸은 훅이 수행한다.\n${approveHint}`);
+                }
+                const call = classifyGithubApiCall(cmd);
+                if (call.kind === "forbidden-client") {
+                    logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter가 비-curl 클라이언트로 GitHub API 접근. cmd="${redactAndTruncate(cmd, 200)}"`);
+                    throw new Error(`[makdoong2-team issue-reporter 게시 게이트] ${call.reason}\n${approveHint}`);
+                }
+                if (call.kind === "mutation") {
+                    if (call.problems.length > 0) {
+                        logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter GitHub 쓰기 형식 위반: ${call.problems.join(" / ")}`);
+                        throw new Error(`[makdoong2-team issue-reporter 게시 게이트] GitHub 쓰기 호출 형식 위반:\n` +
+                            call.problems.map((p) => `  - ${p}`).join("\n") + `\n${approveHint}`);
+                    }
+                    for (const payloadPath of call.payloadPaths) {
+                        if (!existsSync(payloadPath)) {
+                            throw new Error(`[makdoong2-team issue-reporter 게시 게이트] payload 파일이 없다: ${payloadPath}\n${approveHint}`);
+                        }
+                        const markerPath = approvalMarkerPath(payloadPath);
+                        if (!existsSync(markerPath)) {
+                            logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter GitHub 쓰기 — 승인 마커 없음: ${markerPath}`);
+                            throw new Error(`[makdoong2-team issue-reporter 게시 게이트] 사용자 승인이 없다.\n` +
+                                `게시하려는 원문(${payloadPath})을 채팅에 전문 표시한 뒤, 사용자에게 아래 실행을 안내하고 대기하라:\n` +
+                                `  bash ${SCRIPTS_DIR}/${APPROVE_SCRIPT_BASENAME} ${payloadPath}`);
+                        }
+                        const mismatch = approvalMismatch(readFileSync(payloadPath), readFileSync(markerPath, "utf8"));
+                        if (mismatch !== null) {
+                            logger.error(`[makdoong2-team hook] BLOCKED: issue-reporter GitHub 쓰기 — ${mismatch} (${payloadPath})`);
+                            throw new Error(`[makdoong2-team issue-reporter 게시 게이트] ${mismatch}.\n` +
+                                `현재 원문을 다시 채팅에 전문 표시하고 재승인을 받아라:\n` +
+                                `  bash ${SCRIPTS_DIR}/${APPROVE_SCRIPT_BASENAME} ${payloadPath}`);
+                        }
+                        logger.debug(`[makdoong2-team hook] issue-reporter 게시 승인 확인: ${payloadPath} (marker hash 일치)`);
+                    }
+                }
+            }
             const hookIssue = sessionIssue.get(sessionID ?? "") ?? "";
             const r = await runScript(HOOKS_DIR, "guard-bash.sh", cmd, hookIssue);
             if (!r.ok) {
@@ -1064,6 +1149,29 @@ export const Makdoong2TeamPlugin = async ({ $, client, directory, worktree }) =>
                 else
                     sessionActiveToolCount.set(afterSessionID, cur - 1);
             }
+            // ── Issue-reporter 승인 마커 1회용 소멸 ──
+            // GitHub 쓰기 명령이 "실행"되고 나면 결과와 무관하게 마커를 삭제한다.
+            // 성공: 재게시에는 새 승인이 필요하다. 실패(네트워크 등): 같은 원문이라도
+            // 재시도 전에 재승인을 받는다 — 마커를 남겨두면 실패를 빌미로 승인 한 번에
+            // 여러 번의 전송 시도가 가능해지므로 엄격한 쪽을 택했다.
+            if (toolLowerAfter === "bash") {
+                const afterAgent = afterSessionID
+                    ? (sessionAgent.get(afterSessionID) ?? pendingDispatch.get(afterSessionID)?.agent)
+                    : undefined;
+                if (afterAgent === ISSUE_REPORTER_AGENT) {
+                    const afterCmd = input.args?.command ?? "";
+                    const afterCall = classifyGithubApiCall(afterCmd);
+                    if (afterCall.kind === "mutation") {
+                        for (const payloadPath of afterCall.payloadPaths) {
+                            const markerPath = approvalMarkerPath(payloadPath);
+                            if (existsSync(markerPath)) {
+                                rmSync(markerPath, { force: true });
+                                logger.debug(`[makdoong2-team hook] issue-reporter 승인 마커 소멸(1회용): ${markerPath}`);
+                            }
+                        }
+                    }
+                }
+            }
             if (afterSessionID && WRITE_TOOLS.has(toolLowerAfter)) {
                 const agentAfter = sessionAgent.get(afterSessionID)
                     ?? pendingDispatch.get(afterSessionID)?.agent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "makdoong2-team",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -33,6 +33,7 @@
     "dist",
     "src/hooks",
     "agents",
+    "command",
     "gates",
     "stages",
     "references",

package/scripts/install-lib.mjs

@@ -93,6 +93,11 @@ const TOOL_SEARCH_PLUGIN_PREFIX = "opencode-tool-search";
 // and we need the list to remove them without touching unrelated user scripts.
 const UTIL_SCRIPTS = ["state.sh", "rollback-commits.sh", "wt-sync-ignored.sh", "log-event.sh", "config.sh", "model-policy.mjs"];
 const RESEARCH_SKILLS = ["jira-research", "confluence-research", "bitbucket-research", "github-oss-research", "bamboo-ci"];
+// User-invoked utility skills — workflow 밖의 사용자 전용 도구. issue reporter 는
+// /makdoong2-issue-reporter 커맨드(command/ 배포분)로만 트리거되고, 같은 이름의
+// config command 가 opencode 의 skill-derived command 를 덮어써 전용
+// full-permission 에이전트로 라우팅된다.
+const UTILITY_SKILLS = ["makdoong2-issue-reporter"];
 
 // Stale config-dir artifacts left behind by pre-refactor installs. Removed
 // (with backup) at the start of install() so a re-run cleanly migrates users
@@ -315,8 +320,8 @@ export function install(opts) {
   // Create directory structure — only agents/ and research skills/ are deployed.
   // All other runtime assets (gates, scripts, stages, references) live in the
   // npm module and are referenced via resolvePaths() in src/config.ts.
-  const skillDirs = RESEARCH_SKILLS.map((s) => `skills/${s}`);
-  for (const d of ["agents", ...skillDirs]) {
+  const skillDirs = [...RESEARCH_SKILLS, ...UTILITY_SKILLS].map((s) => `skills/${s}`);
+  for (const d of ["agents", "command", ...skillDirs]) {
     mkdirSync(join(configDir, d), { recursive: true });
   }
 
@@ -353,6 +358,35 @@ export function install(opts) {
   }
   ok("research skills (jira/confluence/bitbucket/github-oss/bamboo)");
 
+  // 2b) Utility skills — user-invoked helpers outside the workflow.
+  for (const skill of UTILITY_SKILLS) {
+    const src = join(pkgRoot, "skills", skill);
+    if (!existsSync(src)) continue;
+    const dst = join(configDir, "skills", skill);
+    mkdirSync(dst, { recursive: true });
+    for (const name of readdirSync(src)) {
+      cpSync(join(src, name), join(dst, name));
+      if (name.endsWith(".sh")) chmodSync(join(dst, name), 0o755);
+    }
+  }
+  ok("utility skills (makdoong2-issue-reporter)");
+
+  // 2c) User commands — /makdoong2-issue-reporter 진입점. opencode 는 스킬을
+  // 자동으로 같은 이름의 커맨드로 노출하지만 그 커맨드에는 agent 필드가 없어
+  // 현재 에이전트(권한 제한된 team-leader 등)로 실행된다. cfg.command 가
+  // skill-derived command 보다 우선하므로, 같은 이름의 command 파일을 배포해
+  // 전용 full-permission 에이전트로 라우팅한다.
+  const commandSrc = join(pkgRoot, "command");
+  if (existsSync(commandSrc)) {
+    const commandDst = join(configDir, "command");
+    mkdirSync(commandDst, { recursive: true });
+    for (const name of readdirSync(commandSrc)) {
+      if (!name.endsWith(".md")) continue;
+      cpSync(join(commandSrc, name), join(commandDst, name));
+    }
+    ok("user commands (/makdoong2-issue-reporter)");
+  }
+
   // 3) Config file — seed from default ONLY if absent (never clobber user edits unless --force)
   const cfgPath = join(configDir, "makdoong2-team.json");
   if (!existsSync(cfgPath) || force) {
@@ -839,8 +873,10 @@ function removeOpencodeCache(pkgRoot, { ok, skip, warn }) {
  *
  * What is removed (idempotent — absent targets are silently skipped):
  *   1. Agent definitions: agents/makdoong2-*.md
- *   2. Research skill directories: skills/jira-research, confluence-research, bitbucket-research,
- *      and skills/_lib/ (only when it contains solely our files)
+ *   2. Skill directories: research skills (skills/jira-research, confluence-research,
+ *      bitbucket-research, ...), utility skills (skills/makdoong2-issue-reporter),
+ *      skills/_lib/ (only when it contains solely our files), and deployed
+ *      command files (command/makdoong2-*.md)
  *   3. opencode.json: plugin ref, tools keys, alwaysLoad entries (when
  *      opencode-tool-search is configured), pkgRoot/** external_directory entry
  *   4. opencode plugin cache symlinks seeded by seedOpencodeCache()
@@ -888,10 +924,10 @@ export function uninstall(opts) {
     skip("agents/: directory not found");
   }
 
-  // 2) Research skill directories
-  info("Removing research skills...");
+  // 2) Skill directories (research + utility)
+  info("Removing skills...");
   let skillsRemoved = 0;
-  for (const skill of RESEARCH_SKILLS) {
+  for (const skill of [...RESEARCH_SKILLS, ...UTILITY_SKILLS]) {
     const skillDir = join(configDir, "skills", skill);
     if (!existsSync(skillDir)) continue;
     rmSync(skillDir, { recursive: true, force: true });
@@ -909,9 +945,25 @@ export function uninstall(opts) {
       warn("skills/_lib/ contains unrecognised files — leaving in place");
     }
   }
-  if (skillsRemoved > 0) ok(`${skillsRemoved} research skill director(y/ies) removed`);
+  if (skillsRemoved > 0) ok(`${skillsRemoved} skill director(y/ies) removed`);
   else                   skip("skills/: no makdoong2-team skill directories found");
 
+  // 2b) Deployed command files (only ours — makdoong2-*.md)
+  info("Removing command files...");
+  const cmdDir = join(configDir, "command");
+  if (existsSync(cmdDir)) {
+    let cmdRemoved = 0;
+    for (const name of readdirSync(cmdDir)) {
+      if (!name.startsWith("makdoong2-") || !name.endsWith(".md")) continue;
+      rmSync(join(cmdDir, name), { force: true });
+      cmdRemoved++;
+    }
+    if (cmdRemoved > 0) ok(`${cmdRemoved} command file(s) removed from command/`);
+    else               skip("command/: no makdoong2-*.md files found");
+  } else {
+    skip("command/: directory not found");
+  }
+
   // 3) opencode.json
   info("Patching opencode.json...");
   unpatchOpencodeJson(configDir, pkgRoot, { ok, skip, warn });