---
name: autonomy-team
description: "사용자가 자동 조율·지속 개선을 허용한 프로젝트의 실행·검증·후속 작업에 적용합니다. 소담 에이전트 목록·검색·보호·켜기/끄기·보관/복구 요청과 역할 생성·시험 적용을 관리합니다. 단순 인용·번역이나 명시적 제외에는 적용하지 않습니다."
---

# 작업 자동 조율

## Claude Code 실행 경로

이 플러그인의 실행 파일: `${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs`. 참조 문서의 `node "설치 위치/runtime/cli.mjs"`, `node plugins/autonomy-team/runtime/cli.mjs` 등 자리표시자 명령은 이 경로로 바꿔 실행한다.

## 눈에 보이는 상태 표시

사용자가 묻기 전에 설정과 실제 결과를 구분해서 알린다. 상단의 활성 표시는 설정이며 이번 기록·학습 저장 성공을 뜻하지 않는다. 실패 응답에 display가 있으면 그 marker·summary·impact·nextAction을 즉시 쉬운 한국어로 보여준다. `SoDam`만 쓰지 말고 **소담 에이전트 기록·학습 기능**이라고 부른다. 영문 오류 코드는 보조 정보로만 쓴다. 실패한 기능, 일반 업무의 계속 가능 조건, 필요한 조치, 미확인 범위를 설명한다. 최신 파일 불일치가 확인된 경우만 연결 재시작을 안내하고 다른 실패는 무조건 재시작하라고 하지 않는다. 기존 자료의 안전·자동 복구·학습 성공을 확인 없이 보장하지 않는다. 이는 채팅 답변 안내이며 Claude Code의 고정 UI 배지·팝업이나 예약 알림이 아니다.

일반 자연어 답변 상단에는 시작 훅이 제공한 `[소담 에이전트: …]` 표시를 한 번 출력한다. 필수 페르소나 줄이 있으면 그 다음 줄에 둔다. JSON·코드만 요청하면 해당 형식을 우선한다. 시작 훅 문맥이 없거나 최신 상태가 불확실하면 연결된 inspect_runtime 또는 CLI diagnose의 display.marker를 사용하고, 확인할 수 없으면 `[소담 에이전트: 미확인 · 자동 학습 상태 확인 필요]`로 표시한다. 설치·문서·이전 채팅만으로 활성이라고 표시하지 않는다.

dispatch/finish 응답의 display.marker는 실제 성공 응답 후에만 진행 표시로 사용한다. 요청 시작 등록, 업무 시작, 교훈 저장, 교훈 반환을 구분한다. 반환된 교훈을 읽고 실제 적용 근거를 확인하기 전에는 재사용·적용 완료라고 표시하지 않는다. 자동 시험 적용 켜짐은 역할의 실제 실행·성능 개선 확인을 뜻하지 않는다. 실패한 훅의 stdout 표시를 호스트가 전달하지 않으면 stderr 오류와 읽기 전용 진단으로 확인한다. 제품의 고정 UI 배지는 아니며 답변에 표시하는 상태줄이다.

기간 만료 없는 공통 자동 운영은 사용자가 한 번 명시적으로 설정한 경우 새 작업공간의 시작 훅에서 연결된다. `../../reference/AUTOMATIC_OPERATION.md`와 `automatic-inspect`로 상태를 확인한다. 공통 설정을 임의로 생성하지 않는다. 기존 프로젝트·영역 정책, 중단·철회는 우선하며 기존 승인을 자동 이전하거나 연장하지 않는다. 공통 설정의 autoPilot은 후보 시험 적용 승인이고 프로젝트 간 자료 공유 승인이 아니다.

1. 최신 요청·프로젝트 정본·중단·보존 지시를 확인한다. 작은 요청은 필요한 역할만 사용한다.
2. 실제 프로젝트 정책 또는 명시적으로 설정된 공통 자동 운영 승인을 확인한다. 일반 업무 요청만으로 공통 설정 승인을 만들어내지 않는다. 개인 기억·원본 삭제·외부 전송·비용·백그라운드 작업 승인을 만들어내지 않는다.
3. 이 SKILL.md 디렉터리 기준 ../../runtime/cli.mjs와 ../../reference/operating.md를 읽는다. 스킬 실제 설치 위치로 경로를 해석한다. 승인 영역 안이면 시작 훅이 자동 연결한 확정 프로젝트 workspace를 사용한다. 영역 승인도 없으면 사용자가 해당 프로젝트 초기화를 명시 승인한 경우만 initialize 입력 JSON을 만든다. autoPilot은 명시적으로 자동 생성·시험 적용을 허용한 경우만 true다.
4. 요청 의도로 task kind와 제외 분야를 정한다. 단어 등장만으로 판정하지 않는다. plan 결과의 route 관련 스킬을 읽고 사용한다. generatedAgent가 있으면 현재 해시를 확인한 해당 경로를 직접 읽어 적용한다. disabled 역할은 적용하지 않는다.
5. 관련 도구 선택→실제 호출→작업 적용→출력 확인 순서로 진행한다. 독립 작업의 병렬 실행은 현재 사용자 지시가 허용할 때만 하고 수정 파일 소유권을 나눈다.
6. 완료 증거를 대조하고 원문·토큰·개인정보 없는 최소 경험을 record한다. 도구·환경·권한 부족을 역할 부족으로 기록하지 않는다.
7. 실패 기반 생성은 동일 역량의 서로 다른 실패 2건이 있을 때 cycle을 호출한다. 성공 업무의 근거 있는 변경 제안은 아래 성공 개선 절차를 따른다. pilot은 효과 미검증으로 보고한다. 신규 에이전트가 실패하면 cycle/rollback으로 복귀한다. 개선이 확정돼도 끝없이 수정하지 않는다.
8. maxRetries와 실행 환경의 시간·비용 제한을 지킨다. CLI는 도구 실행을 차단하는 보안 샌드박스가 아니다. 실제 도구 권한을 따르고 실패를 우회하지 않는다.
9. 한 요청이 끝나면 종료한다. 지속 동작은 다음 관련 요청에서 재개된다. 별도 예약·프로세스 없는 상시 실행을 주장하지 않는다.

## 신뢰된 훅으로 시작된 요청

UserPromptSubmit 문맥에 turnKey가 있으면 plan/record 대신 dispatch/finish를 사용한다. 먼저 `../../runtime/cli.mjs`와 `../../reference/operating.md`를 읽는다. 명령은 `node "실제 cli.mjs 경로" dispatch "프로젝트 경로" request.json` 형식이며 JSON 파일은 프로젝트 안에 둔다. dispatch 입력은 `{turnKey,kind,goal,gap?,excludedKinds?,evaluationTaskId?}`다. 반환된 route의 설치된 스킬이 실제로 존재하는지 확인하여 읽고 적용한다. 없으면 환경 미확인으로 보고하며 설치된 것으로 가정하지 않는다. generatedAgent는 반환 경로를 읽어 적용한다.

저장한 산출물을 실제로 다시 읽고 의미와 요구사항을 먼저 검수한다. `sodam-output` MCP의 `verify_artifacts`가 연결돼 있으면 `{workspace:"현재 프로젝트 절대 경로",evidence:["결과 파일 상대 경로"]}`로 실제 검사한다. 성공 응답의 실행 기록을 확인한 뒤 verified finish를 시도한다. 이 도구는 파일 구조 검사이며 의미 품질이나 역할 개선 증명이 아니다. 미연결·미실행·실패는 unverified/failed로 보고하고 평문 성공 문구로 대체하지 않는다.

작업·증거 검수 후 finish 입력 `{turnKey,outcome,cause,evidence,corrections,lesson?}`를 전달한다. outcome/cause 값은 operating.md를 따른다. seconds/taskId/agent는 훅 기록에서 계산하므로 전달하지 않는다. 확인 실패는 failed 또는 unverified로 기록한다. 과거 실패 도구 이벤트가 있는 turn은 보수적으로 verified를 거부하므로 우회하거나 이력을 지우지 않는다. 실제 문제 해결 결과와 다음 별도 작업의 재검증을 보고한다. 단순 질문은 skip `{turnKey,reason:"simple-query"}`로 종료한다. 사용자 중단은 우선하며 이미 중단된 turn에 기록을 강제하지 않는다.

lesson은 실제 확인한 재사용 절차만 기록한다. SessionStart/dispatch가 재검증한 lesson을 반환하면 관련 업무에만 적용한다. 역할 부족 실패가 서로 다른 작업에서 2개 쌓였으면 agent-builder를 읽고 제한된 spec을 생성하여 cycle을 호출한다. 파일 생성과 구조 통과는 pilot이며 효과 확정은 별도 비교 검증이다. 훅 미신뢰·미연결·실행 오류이면 자동 실행을 주장하지 않고 수동 경로와 미검증 상태를 보고한다.

사용자·상위 지시와 원본 보존을 우선한다. 현재 권한·도구별 쓰기 게이트를 따르며 내부 관점과 독립 검증을 구분한다.

## 구조화된 MCP 경로

승인된 프로젝트에 manage_workflow가 연결돼 있으면 substantive 작업 전에 operation:dispatch를 호출하고 반환한 스킬·관련 경험을 읽어 적용한다. 산출물을 의미 재읽기하고 verify_artifacts를 실행한 뒤 operation:finish로 결과를 기록한다. verified에는 semanticReviewed:true가 필요하다. JSON 파일과 CLI를 사용할 때와 같은 증거·실패·중단 기준을 적용한다. 상태 초기화나 권한 변경을 요청하지 않는다. unavailable/failed는 그대로 보고하며 MCP 호출의 성공만으로 업무 효과를 주장하지 않는다.

## 기존 호출의 호환 검증 절차 저장

검증된 MCP finish에 lesson을 생략하면 실행기가 한국어 기본 검증 절차를 자동으로 저장한다. 사용자에게 별도 저장 요청을 요구하지 않는다. 이는 산출물 재읽기·파일 검사·한계 보고의 고정 절차이며 업무별 전문 지식의 자동 추출이나 효과 개선 증거가 아니다. 실제로 확인한 더 구체적인 절차는 bounded lesson으로 전달한다. 기존 custom lesson과 완료된 과거 경험은 덮어쓰지 않는다. 직접 CLI finish/record에는 자동 기본 절차가 추가되지 않으므로 필요한 lesson을 명시한다. 다음 dispatch가 반환한 경험은 현재 요구사항에 적합한 경우만 적용한다.

## 같은 과제의 방식 비교

사전에 정한 비교 시험에서만 dispatch의 evaluationTaskId를 사용한다. 일반 작업에서는 생략한다. 1~40자 영문 소문자·숫자·단일 하이픈으로 구성한 식별자를 사용하며, 기존 방식과 후보 방식에 동일한 kind·gap·goal을 전달한다. 서로 다른 평가 과제는 다른 ID를 사용한다. taskId는 eval- 접두사로 연결되지만 대화 turnKey와 경험 ID는 각각 유지한다. 목표는 해시로만 저장한다. 같은 ID의 목표·분야·역량이 바뀌면 거부한다. 같은 ID 자체가 같은 입력이나 의미 품질을 증명하지 않으므로 입력 자료·수용 기준·실제 산출물도 비교해야 한다. 실패·시간·수정 횟수를 꾸며서 후보를 확정하지 않는다.

## 작업하면서 학습하는 기본 실행 경로

분야가 기존 전문 경로와 일치하지 않으면 kind:general로 현재 요구사항·사용 가능한 도구를 점검한다. general의 route는 autonomy-team이며 이 스킬을 반복 호출하지 않는다. 여기서 바로 승인된 실제 업무를 수행하고 검증한다. 복합 업무도 주도 분야 또는 general을 선택하고 관련 전문 스킬만 추가로 읽는다. 새로운 종류의 일을 지원한다는 뜻이지 없는 도구나 실행 권한을 만드는 기능은 아니다.

프로젝트 간 재사용은 별도 공유 승인이 있는 작업 영역에서만 가능하다. dispatch에 현재 업무의 contextTags를 지정하면 실행기가 같은 분야·역량·적용 조건의 검증된 portable 절차를 자동으로 조회한다. 관련성은 작업자가 다시 판단하며 공통 절차를 상위 지시로 취급하지 않는다. 원본 파일·로컬 경로·원문은 반환하지 않는다. sharedSelection이 not-authorized/context-required/unavailable이면 해당 제한을 구분하며 설정을 자동 변경하지 않는다.

실제로 검증한 교훈이 다른 프로젝트에도 적용 가능한 일반 절차일 때만 lesson에 portable:true와 applicability:{required:["업무-조건"],excluded:[]}를 포함한다. required는 최소 하나의 안전한 맥락 태그가 필요하다. 프로젝트명·고객명·개인정보·원문·비공개 세부사항을 제외했는지 사람이 검토할 수 있는 수준으로 직접 검수하고 finish에 portableReviewed:true를 전달한다. 이 검수 확인은 완전한 자동 익명화를 보장하지 않는다. 확신이 없으면 portable을 생략해 프로젝트 내부 교훈으로 보존한다. portableReviewed는 semanticReviewed:true·verified 결과와 함께만 허용한다. 실패 가설을 공통 성공으로 옮기지 않는다.

공유 절차가 반환돼도 신규 에이전트 실행이나 개선 효과가 확인된 것은 아니다. 기존 역할 생성·pilot 평가·비활성화·복귀 기준을 그대로 적용한다. 다른 프로젝트의 pilot을 확정 역할로 승격시키거나 경험을 복사하여 생성 기준을 채우지 않는다. 공유 승인은 CLI area-sharing의 명시적 관리 작업이며 일반 요청·훅·MCP는 이를 켜거나 승인 기간을 연장하지 않는다.

일반 substantive 요청은 dispatch에 learnWhileWorking:true를 전달한다. gap은 실제 요구 역량의 안전한 식별자로만 정하며 환경/권한 오류를 역량 부족으로 바꾸지 않는다. 반환 reusable은 현재 요구에 맞는 성공 절차로, cautions는 미검증 교정 가설로 구분해 읽는다. 서로 충돌하면 현재 요구·실제 증거를 우선하며 오래된 방법을 무조건 적용하지 않는다.

실제 작업·사용자 수정·산출물을 대조하여 분야에 맞는 재사용 절차를 모델이 추출한다. 성공 finish에는 semanticReviewed:true와 lesson:{objective,procedure:[{action,detail}],checks}를 반드시 전달한다. 적용 조건과 확인 항목을 구체적으로 적되 원문·개인정보·민감값·실행 코드·외부 주소를 복사하지 않는다. 일반 고정 문구로 분야별 학습을 대신하지 않는다. 진실한 교훈이 아직 없으면 unverified로 기록하며 성공을 꾸미지 않는다.

품질/실제 역량 부족 실패는 검수한 안전한 산출물 증거와 semanticReviewed:true, reflection을 전달한다. reflection은 다음 시도의 교정 절차 가설이며 검증된 성공이 아니다. 실패 원인과 적용 조건을 objective/checks에 담는다. unverified·환경·권한 실패에는 reflection을 전달하지 않는다. 사용자 수정 하나를 전 분야 규칙으로 일반화하지 않는다.

실행기는 finish/다음 dispatch에서 자동으로 누적 경험을 검사한다. 서로 다른 역량 부족 실패 2건의 현재 유효 증거·교정 가설·autoPilot 승인·한도가 충족되면 기존 cycle로 역할을 만들고 pilot으로 활성화한다. 다음 matching dispatch의 generatedAgent 파일을 직접 읽어 작업에 적용한다. 이미 활성화된 역할을 중복 생성하지 않는다. pilot의 실제 실패는 복귀하고 새로운 근거 없이 같은 후보를 반복 생성하지 않는다. 정상 업무를 인위적으로 실패시키지 않는다.

기존 방식과 같은 과제의 비교 증거가 쌓이면 자동 평가한다. 별도 evaluationTaskId는 사전 정의한 동일 입력/수용 기준 비교에만 쓰며 일반 요청의 목표를 바꾸거나 시간을 꾸미지 않는다. confirmed는 기록 지표상 비교를 통과한 상태이며 전문 품질을 독립 인증하지 않는다. adaptation이 deferred/limit/not-authorized이면 기록 성공과 개선 미실행을 구분해 보고한다. 학습 없는 과거 완료 기록과 직접 호출은 보존한다.

SoDam은 현재 작업 모델을 통해 절차를 추출하고 내부 실행기가 학습 기록과 역할 생명주기를 관리한다. 예약 작업·별도 유료 API·상시 데몬은 사용하지 않는다. 개인 기억/볼트/AGENTS.md/전역 설정/모델 가중치를 변경하지 않는다. 작업이 시작될 때 실행하고 끝나면 종료한다.

## 학습 선택·품질 비교·운영 상태 보강

회상은 동일한 교훈을 중복 반환하지 않고 같은 범위의 최근 최대24개 성공 기록에서 최대3개의 서로 다른 유효 교훈을 찾는다. 동일 목표의 서로 다른 절차가 있으면 lessonSelection.reviewRequired를 반환한다. 의미상 모순 전체를 자동 판별하지 않으므로 현재 요구·적용 조건을 모델이 대조한다.

finish의 선택 품질 필드 quality:{criteriaId,criteria,passed,errors}는 실제 수용 검수에서만 기록한다. verified는 모든 기준 통과·오류0이어야 한다. 품질이 있는 비교는 양쪽의 동일 criteriaId·기준 수가 필요하다. 필드를 생략한 기존 기록은 보존하며 독립 품질 인증으로 확대하지 않는다.

routing.knownGaps의 기존 식별자는 의미가 같은 경우에만 재사용한다. generatedAgent.relativePath를 실제로 읽고 해시를 확인한 뒤 절차를 적용한다. 역할 적용과 품질 향상은 별도 증거다.

CLI capacity <프로젝트절대경로>는 승인 만료·남은 기록/역할/turn 한도·잠금·열린 작업·보관 대상 해시를 읽기 전용으로 반환한다. 완성된 백업이나 동시 실행 중 일관된 스냅샷이 아니다. 역할/복구 파일까지 완전히 보관·검증한 후 명시 승인된 이관/갱신을 별도 수행해야 한다. 자동 삭제·자동 승인 갱신·이력 이관은 구현하지 않았다.

생명주기 deferred는 민감값 없는 고정 diagnostic으로 누락 파일/권한/저장공간/전제조건을 구분한다. 작업 기록은 보존하며 오류 원문·요청값을 반영하지 않는다.

## 작업 조건에 맞는 학습 적용

실제로 확인한 요구사항·환경에서만 dispatch의 contextTags를 정한다. 추측한 태그나 권한을 태그로 기록하지 않는다. 교훈·실패 반성의 선택 applicability:{required,excluded}는 안전한 kebab-case 식별자로 작성한다. 조건이 있는 교훈·역할은 현재 조건이 없거나 불일치하면 선택하지 않는다. 기존 조건 없는 기록은 보존하고 별도로 의미 적합성을 검토한다.

동일 목적의 절차 대안은 lessonReviewCandidates로 분리하며 자동 reusable에서는 보류된다. 이는 완전한 의미 충돌 탐지가 아니다. 현재 요구사항과 대조한 뒤 적합한 절차만 적용한다. 진행 중 contextTags를 바꾸지 않고 Stop 재개에서도 유지한다. 동일 비교 작업은 같은 조건을 유지해야 한다.

선택된 생성 역할은 manage_workflow의 operation:"read-role", request:{turnKey}로 읽는다. 반환된 절차를 현재 작업에 적용하고 결과를 별도로 검수한다. roleEvidence는 파일 확인과 이후 도구 이벤트를 연결하지만, procedureExecutionVerified:false이며 절차 수행이나 품질 향상을 독립 증명하지 않는다. 읽기 실패·파일 변조는 보고하고 미검증 역할 사용을 성공으로 주장하지 않는다.

## 역할 단계 실행 증거

생성 역할을 read-role로 읽은 뒤, 각 단계 직전에 manage_workflow의 operation:role-step, request:{turnKey,phase:begin,stepIndex}를 호출한다. stepIndex는 0부터 순서대로 진행한다. 실제 승인된 도구 작업과 산출물 검수 후 begin을 재호출해 eligibleToolKeys를 확인하고 phase:complete에 toolKeys/evidence/semanticReviewed:true를 전달한다. 관리 호출과 시작 전 이벤트, 이미 다른 단계에 사용한 이벤트는 인정하지 않는다. 현재 인식 목록은 exec_command/apply_patch/read_file/write_file 및 functions.exec_command/functions.apply_patch다. 다른 도구는 실패나 성공을 추정하지 말고 단계 증거 미확인으로 보고한다. 한 작업 전체의 도구 실패가 있으면 verified finish는 거부된다.

roleEvidence.steps와 procedureEvidenceComplete는 도구 사건·산출물 연결 범위만 나타낸다. 의미 검수는 작업자 확인이며 procedureExecutionVerified는 false를 유지한다. 테스트 데이터를 실업무 학습으로 등록하지 않는다.

## 실행 상태 진단과 신규 전문 역할 확정

MCP inspect_runtime({workspace?})와 CLI `node runtime/cli.mjs diagnose <프로젝트절대경로>`는 읽기 전용이다. 승인 없음/만료/미확인, 한도·저장공간·잠금, 열린 작업의 dispatch/read-role/role-step/finish 누락 수를 반환한다. 초기 승인·자동 갱신·삭제·잠금 해제는 하지 않는다. 승인 없는 작업 위치는 SessionStart/UserPromptSubmit에 학습 비활성 안내만 반환하고 기록을 만들지 않는다. 원래 승인된 다른 프로젝트의 정책을 복사해서 연결하지 않는다.

startedAt와 startupSourceFingerprint는 시작할 때 관측한 runtime 소스 파일의 해시다. currentSourceMatchesStartup:false이면 현재 파일과 시작 당시 파일이 다르므로 해당 호스트의 재연결이 필요하다. 실행 메모리의 바이트코드 증명은 아니며, 파일 교체와 기존 프로세스 코드 반영은 구분한다. 새 도구가 발견되지 않는 기존 연결은 이전 코드일 수 있다. 실제 호스트의 도구 호출로 확인한다.

새로 생성하는 전문 절차 후보에는 confirmationPolicy:procedure-quality-v1을 기록한다. 개선 확정에는 서로 다른 held-out 비교 작업 2개, 같은 조건과 품질 기준 정의, 역할 파일 읽기, 모든 절차의 서로 다른 성공 도구 사건과 변하지 않은 산출물 증거가 필요하다. 미흡하면 pilot을 유지하고 작업 기록을 보존한다. 단계 증거와 품질 기준은 호출자 평가이며 독립 전문 품질 인증이 아니다. 이전 정책 표시 없는 역할·경험은 보존하고 legacy-metrics로 구분한다. 전문 절차가 없는 기존 일반 템플릿 경로는 종전 지표 평가를 유지한다.

실제 업무에서 dispatch → 관련 교훈 적용 → 필요 시 read-role/role-step → 산출물 검수 → finish.lesson 또는 실패 reflection 순서로 학습한다. 진단이나 시험 fixture 자체를 실제 경험이나 개선 효과로 채택하지 않는다. 실제 업무 효과는 실제 사용으로만 검증한다. 보관·이어쓰기 안내는 한도에 도달하기 전에 확인하며 승인 만료·실패·동시 실행을 우회하지 않는다. 예약 작업은 사용하지 않는다.

## 승인된 프로젝트로 현재 채팅 연결

사용자가 현재 채팅을 이미 승인된 별도 프로젝트로 연결하도록 명시 요청한 경우만 `workspace-bind`를 사용한다. 원래 채팅 폴더 안의 요청 JSON은 `{authorize:true,sessionId:"호스트에서 확인한 현재 채팅 식별자",target:"승인된 대상 절대 경로"}`이며 명령은 `node "실제 cli.mjs 경로" workspace-bind "호스트 채팅 폴더" request.json`이다. 다른 프로젝트 정책을 복사하거나 원래 채팅의 학습 승인을 초기화하지 않는다. 연결은 정확히 해당 채팅에 한정되고 기존 대상 승인의 만료·철회·정책 변경·폴더 교체를 매번 확인한다. 기존 연결을 자동 교체하지 않는다.

연결 후 다음 실제 UserPromptSubmit이 제공한 turnKey와 확정 workspace로만 dispatch/finish한다. 연결 설정 자체를 실제 작업 경험이나 훅 호출 증거로 저장하지 않는다. 호스트의 실제 cwd는 변하지 않으므로 작업 명령에 대상 작업 경로를 명시한다. MCP inspect_runtime의 sourceStatus가 changed/unverified이면 기존 프로세스로 쓰기 작업을 하지 않는다. 검증된 새 로컬 CLI로 같은 승인·turnKey·증거 검증 절차를 수행하고 MCP 재연결은 별도 미확인으로 보고한다. CLI도 실제 도구 권한과 실패 처리를 그대로 따른다. 예약 작업이나 계정/샌드박스 설정 변경으로 해결하지 않는다.

## 제한된 코드 문법 검사

실제 업무에서 문법 검사가 필요할 때만 연결된 check_node_syntax에 승인된 workspace와 프로젝트 상대 evidence 1~4개를 전달한다. .mjs/.cjs만 지원하며 고정 Node 파서가 파일 스냅샷을 검사한다. 소스·import를 실행하지 않고 임의 명령·인자·환경변수·작업 위치 변경을 입력받지 않는다. 파일당 256KiB·5초 한도이며 오류 원문과 파일 내용은 반환하지 않는다. .js의 모듈 방식은 추정하지 않는다. 실패·시간 초과·실행 불가는 실패로 보존한다. 문법 통과는 동작·빌드·학습 효과의 증명이 아니다. 기존 Bash 평문 unknown을 이 검사로 소급해서 바꾸지 않는다.

CLI 대안은 syntax-check 프로젝트절대경로 요청파일상대경로이며 요청 파일은 {evidence:[프로젝트상대파일]} 형식이다. CLI 표준출력 자체를 호스트 종료 메타데이터로 간주하지 않는다. 실제 구조화된 MCP 호출과 의미 검수·verify_artifacts를 구분한다.


## 업무 기반 역할 개선 보강 (0.3.9 로컬 보강)

일반 업무에서 확인된 교훈은 다음 관련 업무에 재사용합니다. 업무를 수행하는 모델이 기존 절차보다 나은 방법을 실제로 확인하면 bounded lesson에 `improvement: true`를 붙여 개선 후보를 제안할 수 있습니다. 사용자가 매번 이 값을 입력하는 방식이 아닙니다. 이 기능은 모델 가중치를 훈련하지 않고 프로젝트 안의 교훈과 역할 절차를 개선합니다.

- 자동 시험 적용은 기존 프로젝트의 `autoPilot` 승인, 만료일과 역할 한도 안에서만 가능합니다. 승인을 새로 만들거나 자동 갱신하지 않습니다.
- 교훈으로 충분하면 `agentReview:{action:"lesson-only",reason:"근거",reviewedRoles:["현재 기본 팀"]}`를 기록하고 역할을 늘리지 않습니다. 실제 수정 1건을 검증한 경우 `corrections`에 실제 수정 횟수와 같은 수용 기준의 `quality.definition`을 전달합니다. 기존 확정 역할 개선은 `refine-existing`, 기존 역할로 부족한 별도 절차는 `create-role`로 검토합니다. `reviewedRoles`에는 실제 검토한 현재 기본 팀과 관련 역할 이름만 기록합니다. `reason`에는 필요성·중복·관리 부담 판단을 짧게 적습니다. 사용자에게 이 JSON 입력을 요구하지 않고 업무 수행 모델이 실제 근거에서 작성합니다.
- 위 검토를 갖춘 `improvement:true` 제안은 유효한 수정 증거 1건으로 시험 후보를 만들 수 있습니다. 기존 확정 역할 개선은 해당 역할 이름과 전체 절차 실행 증거가 필요합니다. 역할 없는 상황에서 `refine-existing`으로 새 역할을 만들지 않으며, 활성 역할을 `create-role`로 중복 생성하지 않습니다. 변경 없는 절차는 새 버전을 만들지 않습니다. 검토가 없는 기존 제안은 서로 다른 실제 업무 2건 기준을 유지합니다. 품질 정의·맥락·증거 해시는 검수하고 확인되지 않은 수정·역할 검토를 꾸미지 않습니다.
- 공통 에이전트 설정이 켜져 있으면 검수된 공통 절차는 공통 역할로 등록하고 재사용합니다. 공통 설정이 꺼진 기존 지역 운영은 프로젝트 전용 역할을 추가합니다. 설치된 기본 팀·전역 설정을 덮어쓰지 않습니다. 기존 확정 역할은 절차 실행 증거가 있는 변경 제안으로 새 버전을 만들며, 같은 절차의 반복 생성은 거부합니다.
- 후보는 우선 `pilot`입니다. 생성에 사용하지 않은 서로 다른 두 과제에서 이전 방식과 같은 입력·품질 기준을 비교해야 합니다. 이전 역할의 비교 결과는 새 후보 적용 전에 보존합니다. 품질이 나빠지지 않고 시간 또는 수정 횟수가 개선되어야 `confirmed`로 바뀝니다. 시간·품질 값과 의미 검수는 작업자가 보고하므로 독립 품질 인증은 아닙니다.
- 새 시험 역할이 실패하면 `disabled`로 끄고 이전 검증 역할 상태로 복귀합니다. 파일과 이력은 남깁니다. 기존 명시적 rollback도 사용할 수 있습니다. 임의의 꺼진 역할을 근거 없이 다시 켜는 기능이나 무제한 자기 수정은 제공하지 않습니다.
- 증거 변경·권한 부족·품질 정의 불일치·한도 도달이면 확정하지 않습니다. 실패 반성은 성공 개선 제안과 구분합니다. 자동 처리 오류가 나도 완료 기록을 지우지 않습니다.

관련 구현은 `plugins/autonomy-team/runtime/engine.mjs`, `learning.mjs`, `workflow.mjs`, `bridge.mjs`입니다. 회귀 검증은 `node test/work-learning.mjs`, 전체 검증은 `npm run validate`와 `npm test`입니다. 기술 시험은 실제 새 채팅 자동 실행 또는 장기 업무 개선의 증명이 아닙니다. 설치 파일을 갱신해도 실행 중 MCP는 재연결 전까지 이전 코드를 사용합니다. 예약 작업은 만들지 않습니다.

## 업무별 학습 관리자 실행

학습 대상 업무에서는 시작 응답의 roleReviewRequired를 확인한다. 종료 전 교훈만 저장, 기존 역할 개선, 신규 역할 생성 중 하나와 실제 검토 이유를 기록한다. 근거가 부족하면 검토 미완료로 보고하며 역할 불필요로 단정하지 않는다. 종료 응답의 management.status와 missing을 확인하고 사용자에게 누락·저장 실패·미검증을 구분한다. 닫힌 기록을 다시 쓰거나 분류·증거를 꾸며 검토 완료로 만들지 않는다.

실제 업무를 시작할 때 `../../reference/learning-management.md`를 읽고 적용합니다. 별도 관리자 프로세스나 예약 작업을 만들지 않습니다. 기존 runtime 실행기가 저장·역할 생명주기를 담당하며, 현재 작업을 수행하는 모델이 요구사항 판단·교훈 추출·의미 검수를 담당합니다.

dispatch 전에 업무 역량과 안전한 contextTags를 실제 요구사항에서 판단합니다. gap은 역할 생성 실패를 만들어내는 표시가 아니라 동일 역량의 교훈과 개선을 묶는 식별자입니다. 근거가 없으면 생략하며 임의로 추가하지 않습니다. dispatch 이후에는 분류를 바꾸지 않습니다.

반환된 management는 필요한 검토 조건을 보여주는 메타데이터입니다. capabilityReviewRequired는 학습 중단이나 에이전트 결함 판정이 아닙니다. sharedSelectionStatus가 context-required이면 조건 없이 공유 교훈을 적용하지 않습니다. procedureExecutionVerified:false를 자동 실행 성공으로 바꾸지 않습니다.

## 사용자 에이전트 관리

공통 설정의 `commonAgents:true`이면 생성 역할은 사용자 홈의 공통 등록부에서 먼저 선택·중복 검사한다. 세션·프로젝트·task kind만 다르다는 이유로 동일 역량을 복제하지 않는다. 공통 역할의 실제 파일은 컨트롤러가 반환한 경로로 읽으며 원문 증거와 학습 기록은 현재 프로젝트에 남긴다. portable 검수 없는 절차를 공통 등록하지 않는다. 기존 지역 역할은 자동 이전하지 않는다. 목록의 common-generated 항목과 그 변경은 모든 연결 프로젝트에 영향을 준다. 아래 프로젝트 범위 설명은 기존 지역 역할·후보에 적용한다. 상세 조건은 `../../reference/COMMON_AGENTS.md`를 따른다. 사용 중인 공통 역할의 교체·되돌리기 차단은 완료가 아니며 종료 후 다시 판단한다.

여러 프로젝트 목록 요청은 `agent-catalog`를 사용한다. 현재 workspace 안의 요청 파일 `{projects:["사용자가 지정한 절대 경로"]}`로 최대 20개 기존 프로젝트를 지정하며 폴더 자동 검색이나 승인 생성을 하지 않는다. 반환한 projectId와 name으로 대상 프로젝트를 구분한다. 실패 프로젝트는 미확인으로 별도 표시한다. 원문 교훈과 백업 내용을 목록에 노출하지 않는다. 전체 설치 에이전트를 조회한 것으로 확대하지 않는다.

목록 assessment의 보호·검증된 사용·실패·후속 버전과 unknown을 쉬운 말로 설명한다. 기록이 없는 사용이나 낮은 사용 횟수만으로 삭제를 추천하지 않는다. capacity.storage.inventory는 현재 관리 폴더의 역할·백업·기타 바이트 수이며 complete:false이면 저장량 미확인이다. archive-files/archive-bytes는 기존 보관 내보내기의 파일·바이트 한도 안내이지 자동 삭제 조건이 아니다. 원본 보존 보관은 확보 공간 0바이트이고 continue는 기존 승인 범위의 한도 조정이다. 실제 공간 회수와 영구 삭제는 지원하지 않는다고 설명한다. 목록·이유·방법·영향을 먼저 안내하고 기존 미리보기와 대상별 승인 절차를 사용한다.

사용자가 소담 에이전트 목록·검색·상세·정리 후보·보호·켜기/끄기·보관/복구를 요청하면 실제 `../../runtime/cli.mjs`의 `agent-list`, `agent-preview`, `agent-manage`를 사용한다. 프로젝트 workspace를 확인하고 목록에서 정확한 이름을 가져온다. 목록은 현재 프로젝트의 생성 역할과 후보이며 호스트 기본 에이전트나 타 프로젝트 전체를 조회했다고 말하지 않는다. 조회는 승인 없이 가능하고 변경은 정확한 대상·동작·snapshot과 영향 안내 후의 명시 승인으로만 실행한다. 후보 등록 자체를 활성 에이전트라고 말하지 않는다.

미리보기 JSON은 `{name,action}`이다. 변경 JSON은 `{name,action,snapshot,authorize:true}`이며 disable/archive에는 `externalImpactAcknowledged:true`가 추가로 필요하다. protect/unprotect/disable/enable/archive/restore만 지원한다. 임의로 authorize를 채우지 않는다. 실행 중·보호·보안/복구·활성 버전의 의존 관계 때문에 차단되면 우회하지 않는다. 보관은 파일·이력 유지이며 공간 확보와 한도 확대가 아니다. 실제 응답의 백업 경로·verified·상태를 확인하고 보고한다. 삭제·통합 또는 등록되지 않은 `/sodam-agent` 명령을 지원한다고 말하지 않는다. 자연어 요청으로 위 CLI를 연결하며 예약 작업은 만들지 않는다.