@asc-agent/runtime 0.2.1 → 0.3.0

package/dist/core/operator/contract-draft.js

@@ -0,0 +1,234 @@
+// Session Contract Drafting — 자연어 업무 요청과 세션 계약 사이의 빈 칸 (C-04 · C-13).
+//
+// **왜 필요한가**: ASC는 완성된 계약을 실행·통제하는 데는 강한데, 사람이 "ABC-123 구현해"
+// 라고 말한 것을 계약으로 바꾸는 자리에 규약이 없었다. 그래서 두 가지 중 하나가 일어났다 —
+// agent가 goal·boundary·criteria를 통째로 지어내거나(fail-closed 위반), 아니면 넷을 전부
+// 사람에게 입력하라고 되물었다(자율성 포기). 둘 다 틀렸다.
+//
+// **여기서 하는 일과 하지 않는 일**:
+//   한다   — agent가 만든 초안을 **검증**한다. 무엇이 사실이고 무엇이 추론인지 갈라 두고,
+//            사람만 정할 수 있는 것이 남았는지 판정한다.
+//   안 한다 — 초안을 만들지 않는다. 계약을 발급하지 않는다. LLM을 품지 않는다.
+//            해석은 coding agent가 하고, 이 모듈은 그 결과를 구조·정책으로 잰다.
+//
+// 판정 로직을 새로 만들지 않는다. 경로 축은 preflight, 책임 축은 ownership, 문법은 scope,
+// 사람에게 넘길 사유는 escalation predicate — 전부 이미 있는 것을 부른다.
+import { z } from 'zod';
+import { EscalationPredicate } from "../runtime/escalation.js";
+import { SessionRole } from "../model/entities.js";
+import { SessionId } from "../model/ids.js";
+import { isWithinScopes, parseScope } from "../policy/scope.js";
+import { lookupOwnerByPaths } from "../policy/ownership.js";
+import { preflight } from "./preflight.js";
+/** 값이 어디서 왔는지. 지어낸 것과 읽어 온 것을 문자열 하나로 구분한다. */
+// provider 이름을 적지 않는다 (C-09 §6.1). 어느 tracker의 항목인지는 Adapter가 알고,
+// 계약 초안이 아는 것은 "추적 항목에서 읽었다"까지다.
+export const DRAFT_SOURCES = ['user', 'work_item', 'profile', 'repository', 'canonical', 'agent_proposal'];
+/** 초안의 출처 한 줄. CLI가 받는 문자열도 이 스키마로 통과시켜야 들어온다. */
+export const DraftProvenance = z.object({
+    field: z.enum(['id', 'role', 'goal', 'boundary', 'criteria', 'owner']),
+    status: z.enum(['FACT', 'PROPOSAL', 'DECISION_REQUIRED']),
+    source: z.enum(DRAFT_SOURCES),
+    /** 왜 이 값인가. PROPOSAL이면 반드시 있어야 한다 — 근거 없는 제안은 추측이다. */
+    reason: z.string().min(1).optional(),
+});
+/**
+ * 발급 권한은 **사람의 것이다** (OM §450). 다만 그 문장이 "매번 사람이 직접 쳐야 한다"는
+ * 뜻은 아니다 — Controller가 **범위를 정해 위임**할 수 있고, 그 범위 안에서만 agent가
+ * 스스로 발급한다. 위임이 없으면 계약이 완성돼도 발급하지 않고 사람에게 넘긴다.
+ *
+ * 위임은 Profile/Override의 `policy.unionLists.issuanceDelegation` 에 **역할 이름**으로
+ * 적는다 (closureChecklist와 같은 관례 키 자리). 경로 범위는 이미 `roleScopes` 가 좁히고
+ * 있으므로 여기서 다시 정의하지 않는다 — 권한을 두 곳에 적으면 둘이 갈라진다.
+ */
+export const ISSUANCE_DELEGATION_KEY = 'issuanceDelegation';
+const provenanceOf = (draft, field) => draft.provenance?.find((entry) => entry.field === field);
+/**
+ * 초안을 잰다. **아무것도 쓰지 않는다** — 순수 함수이고, 같은 입력이면 같은 답이다.
+ *
+ * 판정 순서에 뜻이 있다: 먼저 구조(문법·필수값)를 보고, 그 다음 경계(범위·책임)를 본다.
+ * 구조가 깨진 초안의 경계를 논하는 것은 의미가 없고, 사람에게 두 번 묻게 만든다.
+ */
+export function planSessionContract(input) {
+    const { draft, policy, ownership, existingIds } = input;
+    const facts = [];
+    const proposals = [];
+    const unresolved = [];
+    const invalid = [];
+    const classify = (field, present) => {
+        if (!present)
+            return;
+        const entry = provenanceOf(draft, field);
+        if (!entry) {
+            // 출처를 적지 않은 값은 사실로 세지 않는다. 어디서 왔는지 모르는 값이
+            // 계약에 박히면, 나중에 그것이 틀렸을 때 무엇을 되짚어야 하는지 아무도 모른다.
+            proposals.push({ field, status: 'PROPOSAL', source: 'agent_proposal', reason: 'source not declared' });
+            return;
+        }
+        if (entry.status === 'FACT')
+            facts.push(entry);
+        else if (entry.status === 'PROPOSAL')
+            proposals.push(entry);
+        else
+            unresolved.push({
+                field,
+                reason: 'explicit_rule_requires_approval',
+                detail: entry.reason ?? `${field} is marked as a decision for a person`,
+            });
+    };
+    // ── 구조 ────────────────────────────────────────────────────────────────
+    if (draft.id === undefined) {
+        unresolved.push({
+            field: 'id',
+            reason: 'missing_input',
+            detail: 'No session id. Use the work item key the person named, or the task id the canonical source ties to' +
+                ' this work. Do not spend a real issue key on a setup check.',
+        });
+    }
+    else if (!SessionId.safeParse(draft.id).success) {
+        invalid.push({ field: 'id', detail: `'${draft.id}' is not a session id — expected S-YYYYMMDD-NN` });
+    }
+    else if (existingIds?.includes(draft.id)) {
+        invalid.push({ field: 'id', detail: `session ${draft.id} already exists` });
+    }
+    classify('id', draft.id !== undefined);
+    if (draft.role === undefined) {
+        unresolved.push({ field: 'role', reason: 'missing_input', detail: 'No role. Which part of the work is this?' });
+    }
+    else if (!SessionRole.safeParse(draft.role).success) {
+        invalid.push({ field: 'role', detail: `'${draft.role}' is not a role — expected one of ${SessionRole.options.join(', ')}` });
+    }
+    classify('role', draft.role !== undefined);
+    if (!draft.goal || draft.goal.trim() === '') {
+        unresolved.push({
+            field: 'goal',
+            reason: 'missing_input',
+            detail: 'No goal. Take it from what the person asked for, or from the requirement the work item states.',
+        });
+    }
+    classify('goal', Boolean(draft.goal && draft.goal.trim() !== ''));
+    for (const entry of draft.boundary ?? []) {
+        if (parseScope(entry) === null)
+            invalid.push({ field: 'boundary', detail: `'${entry}' is not valid ASC scope grammar` });
+    }
+    if ((draft.boundary ?? []).length === 0) {
+        unresolved.push({
+            field: 'boundary',
+            reason: 'missing_input',
+            detail: 'No write boundary. Propose the narrowest set that covers the work — a boundary is what the session may' +
+                ' write, not what it may read.',
+        });
+    }
+    classify('boundary', (draft.boundary ?? []).length > 0);
+    if ((draft.criteria ?? []).length === 0) {
+        unresolved.push({
+            field: 'criteria',
+            reason: 'missing_input',
+            detail: 'No done-criteria. Collect them from the acceptance the work item states, the canonical spec, or the' +
+                ' checks this repository already runs. Do not invent new product acceptance.',
+        });
+    }
+    classify('criteria', (draft.criteria ?? []).length > 0);
+    classify('owner', draft.owner !== undefined);
+    // ── 경계 ────────────────────────────────────────────────────────────────
+    // 구조가 깨졌으면 여기서 멈춘다. 틀린 초안의 범위를 따져도 답이 두 번 바뀔 뿐이다.
+    const role = draft.role !== undefined && SessionRole.safeParse(draft.role).success ? draft.role : undefined;
+    const boundary = draft.boundary ?? [];
+    let report;
+    if (invalid.length === 0 && role && boundary.length > 0) {
+        const maxScope = policy?.roleScopes[role];
+        for (const entry of boundary) {
+            if (maxScope && !isWithinScopes(entry, maxScope)) {
+                // 범위를 넓혀 해소하지 않는다 (preflight와 같은 자세). 이건 사람의 경계다.
+                unresolved.push({
+                    field: 'boundary',
+                    reason: 'ownership_boundary',
+                    detail: `${role} may not write '${entry}' — outside ${maxScope.join(', ')}`,
+                    options: [`narrow the boundary to ${maxScope.join(', ')}`, 'hand this part to the role that owns it', 'ask for the scope to be widened'],
+                    recommended: 0,
+                });
+            }
+        }
+        report = preflight({
+            paths: boundary,
+            target: {
+                kind: 'session',
+                // 아직 발급하지 않았다. preflight는 이 id를 조회하지 않고 문장에만 쓴다.
+                sessionId: draft.id ?? '(draft)',
+                role,
+                writeBoundary: boundary,
+                ...(draft.owner ? { owner: draft.owner } : {}),
+                ...(draft.decisionDomains ? { decisionDomains: draft.decisionDomains } : {}),
+                ...(draft.decisionAuthority ? { decisionAuthority: draft.decisionAuthority } : {}),
+            },
+            ...(policy ? { policy } : {}),
+            ...(ownership ? { ownership } : {}),
+        });
+        for (const mismatch of report.mismatches) {
+            if (mismatch.verdict !== 'OWNERSHIP_MISMATCH')
+                continue;
+            unresolved.push({
+                field: 'boundary',
+                reason: 'ownership_boundary',
+                detail: `'${mismatch.path}' is inside the boundary but outside ${draft.owner}'s declared paths`,
+            });
+        }
+        for (const gap of report.authorityGaps) {
+            unresolved.push({
+                field: 'owner',
+                reason: 'ownership_boundary',
+                detail: gap.lookup.kind === 'AMBIGUOUS'
+                    ? `more than one part claims '${gap.domain}': ${gap.lookup.candidates.join(', ')}`
+                    : `no part declares authority over '${gap.domain}'`,
+                ...(gap.lookup.kind === 'AMBIGUOUS'
+                    ? { options: [...gap.lookup.candidates], recommended: undefined }
+                    : {}),
+            });
+        }
+        // owner를 적지 않았는데 경계로 주인을 특정할 수 있으면, 그것은 질문이 아니라 제안이다.
+        if (!draft.owner && ownership) {
+            const owner = lookupOwnerByPaths(ownership, boundary);
+            if (owner.kind === 'RESOLVED') {
+                proposals.push({ field: 'owner', status: 'PROPOSAL', source: 'profile', reason: `boundary falls inside ${owner.role}` });
+            }
+            else if (owner.kind === 'AMBIGUOUS') {
+                unresolved.push({
+                    field: 'owner',
+                    reason: 'multiple_options',
+                    detail: 'more than one part covers this boundary',
+                    options: [...owner.candidates],
+                    recommended: 0,
+                });
+            }
+        }
+    }
+    const status = invalid.length > 0 ? 'INVALID' : unresolved.length > 0 ? 'NEEDS_DECISION' : 'READY_TO_ISSUE';
+    // Profile은 `policy.unionLists` 로 선언하고, 계층 병합이 끝나면 `lists` 로 온다.
+    const delegatedRoles = [...(policy?.lists?.[ISSUANCE_DELEGATION_KEY] ?? [])];
+    const delegated = role !== undefined && delegatedRoles.includes(role);
+    const issuance = {
+        authority: delegated ? 'delegated' : 'controller',
+        delegatedRoles,
+        detail: delegated
+            ? `the Controller delegated issuance for ${role}`
+            : delegatedRoles.length > 0
+                ? `issuance is delegated for ${delegatedRoles.join(', ')} — not for ${role ?? '(no role)'}`
+                : 'issuance belongs to the Controller; no role has been delegated',
+    };
+    return { status, draft, facts, proposals, unresolved, issuance, invalid, ...(report ? { preflight: report } : {}) };
+}
+/** 발급 명령의 인자. plan이 통과했을 때만 부른다 — 통과하지 않은 초안은 명령이 되지 않는다. */
+export function issueArgs(draft) {
+    const args = ['session', 'issue', draft.id ?? '<ID>', '--role', draft.role ?? '<role>', '--goal', draft.goal ?? '<goal>'];
+    for (const entry of draft.boundary ?? [])
+        args.push('--boundary', entry);
+    for (const entry of draft.criteria ?? [])
+        args.push('--criteria', entry);
+    if (draft.owner)
+        args.push('--owner', draft.owner);
+    for (const domain of draft.decisionDomains ?? [])
+        args.push('--domain', domain);
+    for (const [domain, holder] of Object.entries(draft.decisionAuthority ?? {}))
+        args.push('--authority', `${domain}=${holder}`);
+    return args;
+}

package/dist/core/operator/derive-draft.d.ts

@@ -0,0 +1,37 @@
+import type { RepoObservation } from '../../ports/local-repo.ts';
+import type { ResourceSnapshot } from '../../ports/resource-context.ts';
+import type { OwnershipMap } from '../policy/ownership.ts';
+import type { SessionContractDraft } from './contract-draft.ts';
+import type { WorkStateResult } from './work-state.ts';
+export type DeriveInput = {
+    intent: {
+        /** 사람이 지목한 작업 항목 키. */
+        workRef: string;
+        /** 사람이 직접 말한 목표가 있으면. 없으면 작업 항목에서 읽는다. */
+        goal?: string;
+        role?: string;
+    };
+    workItem: ResourceSnapshot;
+    workState: WorkStateResult;
+    repo: RepoObservation | 'MISSING';
+    /**
+     * 이 역할이 **가질 수 있는 최대 범위** (Profile roleScopes).
+     *
+     * 여기서 boundary 를 만들지 않는다 — 상한과 이번 작업의 쓰기 범위는 다른 것이다.
+     * "전체까지 허용될 수 있다"가 "이번 작업이 전체를 고친다"를 뜻하지 않는다. 이 값은
+     * 도출한 후보가 상한을 넘지 않는지 **재는 데만** 쓴다.
+     */
+    maxScopes?: readonly string[];
+    ownership?: OwnershipMap;
+    existingIds?: readonly string[];
+    /** YYYYMMDD. 세션 id 는 날짜를 담는다 (S-YYYYMMDD-NN). */
+    today: string;
+    /** 저장소가 이미 돌리는 검사들 (예: 'npm test'). 검증 기준의 근거가 된다. */
+    repoChecks?: readonly string[];
+};
+export declare function deriveSessionContractDraft(input: DeriveInput): SessionContractDraft;
+/** 작업 항목이 가리키는 경로 후보. 실존 여부는 저장소가 답한다 — 여기서는 줍기만 한다. */
+export declare function extractPathHints(workItem: {
+    title?: string;
+    body?: string;
+}): string[];

package/dist/core/operator/derive-draft.js

@@ -0,0 +1,216 @@
+// 조사 결과 → 계약 초안 (P0-C).
+//
+// contract-draft.ts 는 "초안을 만들지 않는다"고 선언한다. 맞는 선언이지만, 그러면 초안을
+// 만드는 자리가 어디에도 없어서 사람이 goal·boundary·criteria 를 손으로 채우거나 agent 가
+// 지어냈다. 이 모듈이 그 빈 칸이다 — **읽어 온 사실로 채울 수 있는 만큼만 채우고, 나머지는
+// 비운 채로 넘긴다.**
+//
+// 판정은 하지 않는다. 범위가 맞는지, 책임자가 누구인지, 사람이 정해야 하는지는 전부
+// planSessionContract 가 이미 잰다. 여기서 같은 것을 또 재면 두 판정이 갈라진다.
+//
+// 순수 함수다. 날짜조차 주입받는다.
+import { isWithinScopes } from "../policy/scope.js";
+/**
+ * 완료 조건으로 읽을 만한 줄. 헤딩 아래 불릿·체크박스만 본다 — 문장을 해석하지 않는다.
+ * 못 찾으면 **비운다**. 없는 인수 조건을 만들어 넣는 것이 이 함수가 할 수 있는 최악이다.
+ */
+const ACCEPTANCE_HEADING = /(완료\s*조건|인수\s*조건|acceptance|done\s*criteria)/i;
+// 불릿·번호·체크박스 어느 형태든 항목으로 본다. 추적 도구마다 본문을 다르게 눌러 담는다 —
+// 마크다운을 그대로 주는 곳도 있고, 헤딩·불릿 기호를 떼고 평문으로 주는 곳도 있다.
+const BULLET = /^\s*(?:[-*+]\s*)?(?:\[[ xX]\]\s*)(.+?)\s*$|^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$/;
+/** 짧고 항목이 아닌 줄은 구획 이름으로 읽는다 (`### 완료 조건` 도, 평문 `완료 조건` 도). */
+const SECTION_LABEL = /^\s{0,3}(?:#{1,6}\s*|\*\*)?([^\n]{1,30}?)(?:\*\*)?\s*$/;
+export function deriveSessionContractDraft(input) {
+    const provenance = [];
+    const draft = {};
+    // ── id ── 작업 항목 키는 세션 id 가 될 수 없다 (SessionId 는 S-YYYYMMDD-NN). 키는
+    //          goal 과 provenance 에 남고, 세션 id 는 오늘 날짜로 새로 뽑는다.
+    draft.id = nextSessionId(input.today, input.existingIds ?? []);
+    provenance.push({
+        field: 'id',
+        status: 'PROPOSAL',
+        source: 'agent_proposal',
+        reason: `${input.intent.workRef} 작업을 위해 오늘 날짜로 뽑은 세션 id`,
+    });
+    // ── role ──
+    if (input.intent.role) {
+        draft.role = input.intent.role;
+        provenance.push({ field: 'role', status: 'FACT', source: 'user', reason: '사람이 역할을 지정했다' });
+    }
+    else {
+        draft.role = 'implementer';
+        provenance.push({
+            field: 'role',
+            status: 'PROPOSAL',
+            source: 'agent_proposal',
+            reason: `${input.intent.workRef} 착수 요청이라 구현 역할로 제안한다`,
+        });
+    }
+    // ── goal ── 작업 항목이 말하는 것을 옮긴다. 다시 쓰지 않는다.
+    if (input.intent.goal && input.intent.goal.trim() !== '') {
+        draft.goal = input.intent.goal.trim();
+        provenance.push({ field: 'goal', status: 'FACT', source: 'user', reason: '사람이 목표를 직접 말했다' });
+    }
+    else {
+        draft.goal = `${input.workItem.reference}: ${input.workItem.title}`;
+        provenance.push({
+            field: 'goal',
+            status: 'FACT',
+            source: 'work_item',
+            reason: '작업 항목의 제목을 그대로 옮겼다',
+        });
+    }
+    // ── boundary ── **이번 작업이 쓸 범위**를 작업 근거에서 만든다. 역할의 최대 범위를
+    //                복사하지 않는다 — 정책이 없다는 것은 전체를 써도 된다는 뜻이 아니고,
+    //                정책이 `**` 를 허용한다는 것도 이번 작업이 전체를 고친다는 뜻이 아니다.
+    //                근거가 끝까지 없으면 **비운다** — planSessionContract 가 사람에게 묻는다.
+    const boundary = deriveBoundary(input);
+    if (boundary) {
+        draft.boundary = boundary.scopes;
+        provenance.push({ field: 'boundary', status: 'PROPOSAL', source: 'repository', reason: boundary.reason });
+    }
+    // ── criteria ── 작업 항목의 완료 조건은 사실이고, 저장소가 이미 돌리는 검사는 제안이다.
+    //                둘 다 없으면 비운다. planSessionContract 가 사람에게 묻게 두는 편이,
+    //                없는 인수 조건을 지어내는 것보다 낫다.
+    const fromItem = acceptanceLines(input.workItem.body);
+    const fromRepo = (input.repoChecks ?? []).map((check) => `저장소 기존 검사 통과: ${check}`);
+    const criteria = [...fromItem, ...fromRepo];
+    if (criteria.length > 0) {
+        draft.criteria = criteria;
+        provenance.push({
+            field: 'criteria',
+            status: fromItem.length > 0 ? 'FACT' : 'PROPOSAL',
+            source: fromItem.length > 0 ? 'work_item' : 'repository',
+            reason: fromItem.length > 0
+                ? '작업 항목이 적어 둔 완료 조건을 옮겼다'
+                : '작업 항목에 완료 조건이 없어 저장소가 이미 돌리는 검사를 제안한다',
+        });
+    }
+    // owner 는 여기서 정하지 않는다 — planSessionContract 의 lookupOwnerByPaths 가 이미 한다.
+    draft.provenance = provenance;
+    return draft;
+}
+/** 다음 세션 id. 같은 날 이미 쓴 번호는 건너뛴다. */
+function nextSessionId(today, existing) {
+    const used = new Set(existing
+        .map((id) => /^S-(\d{8})-(\d{2})$/.exec(id))
+        .filter((m) => m !== null && m[1] === today)
+        .map((m) => Number(m[2])));
+    let n = 1;
+    while (used.has(n))
+        n += 1;
+    return `S-${today}-${String(n).padStart(2, '0')}`;
+}
+/**
+ * 참고로 읽는 곳이지 고치는 곳이 아닌 경로. 작업 항목이 spec 을 가리킨다고 해서 그 spec 을
+ * 고치라는 뜻이 아니다 — 읽기 근거를 쓰기 범위로 승격하면 계약이 조용히 넓어진다.
+ */
+const READ_ONLY_PREFIXES = ['specs/', 'docs/', 'reference/'];
+const isReadOnlyReference = (path) => READ_ONLY_PREFIXES.some((prefix) => path === prefix.slice(0, -1) || path.startsWith(prefix));
+/** 경로처럼 생긴 토큰. 문장을 해석하지 않는다 — `a/b`, `a/b/c.ts` 만 줍는다. */
+const PATH_TOKEN = /(?<![\w/@])([\w.-]+(?:\/[\w.*-]+)+)/g;
+/** 작업 항목이 가리키는 경로 후보. 실존 여부는 저장소가 답한다 — 여기서는 줍기만 한다. */
+export function extractPathHints(workItem) {
+    const text = `${workItem.title ?? ''}\n${workItem.body ?? ''}`;
+    const found = new Set();
+    for (const [, token] of text.matchAll(PATH_TOKEN)) {
+        if (!token)
+            continue;
+        const cleaned = token.replace(/[.,)\]]+$/, '');
+        // URL 조각과 버전 표기는 경로가 아니다.
+        if (/^https?:/.test(cleaned) || /^\d+\/\d+$/.test(cleaned))
+            continue;
+        if (isReadOnlyReference(cleaned))
+            continue;
+        found.add(cleaned);
+    }
+    return [...found];
+}
+/**
+ * 근거의 순서가 곧 좁은 정도의 순서다: 작업 항목이 지목한 것 → 저장소에서 확인된 구현
+ * 영역 → 이름이 유일하게 맞아떨어지는 모듈. 어느 단계든 **상한(maxScopes) 밖이면 버린다.**
+ */
+function deriveBoundary(input) {
+    if (input.repo === 'MISSING')
+        return null;
+    const repo = input.repo;
+    const within = (scope) => (input.maxScopes?.length ?? 0) === 0 ? true : isWithinScopes(scope, [...(input.maxScopes ?? [])]);
+    const present = Object.entries(repo.pathsExist)
+        .filter(([, exists]) => exists)
+        .map(([path]) => path);
+    // 모듈 목록은 범위를 좁히는 재료다 — 판정의 증거가 아니므로 여기서만 본다.
+    const modules = Object.entries(repo.modulesPresent ?? {})
+        .filter(([, exists]) => exists)
+        .map(([path]) => path);
+    // ① 작업 항목이 지목했고 저장소에 실제로 있는 경로.
+    const named = extractPathHints(input.workItem).filter((hint) => present.includes(hint));
+    const fromItem = [...new Set(named.map(toScope))].filter(within);
+    if (fromItem.length > 0) {
+        return { scopes: fromItem, reason: '작업 항목이 지목했고 저장소에 실재하는 경로로 좁혔다' };
+    }
+    // ② 분류 이름이 **유일하게** 맞아떨어지는 모듈. 후보가 둘 이상이면 고르지 않는다.
+    const module = uniqueModule(input.workItem.labels ?? [], [...present, ...modules]);
+    if (module && within(module)) {
+        return { scopes: [module], reason: '작업 항목의 분류와 이름이 유일하게 맞는 모듈로 좁혔다' };
+    }
+    // ③ 저장소에서 확인된 구현 경로. 최상위 디렉터리는 쓰지 않는다 — 그 깊이는 "이 저장소"와
+    //    거의 같은 말이고, 조회 목록이 곧 권한이 되는 것을 막는다. 갈래가 많으면 좁힌 것이
+    //    아니므로 그때도 비운다.
+    const deep = [
+        ...new Set(present.filter((path) => path.split('/').length >= 2 && !isReadOnlyReference(path)).map(toScope)),
+    ].filter(within);
+    if (deep.length > 0 && deep.length <= 3) {
+        return { scopes: deep, reason: '저장소에서 확인된 구현 경로로 좁혔다' };
+    }
+    return null;
+}
+const toScope = (path) => {
+    if (path.endsWith('/**'))
+        return path;
+    // 파일이면 그 파일이 사는 자리까지. 디렉터리면 그 아래.
+    const isFile = /\.[A-Za-z0-9]+$/.test(path);
+    const base = isFile ? path.slice(0, path.lastIndexOf('/')) : path.replace(/\/$/, '');
+    return base === '' ? path : `${base}/**`;
+};
+const normalize = (value) => value.toLowerCase().replace(/[^a-z0-9]/g, '');
+/**
+ * 분류 이름 하나가 저장소의 어느 자리 하나에만 맞을 때만 답한다. 범용 유사도 매칭을
+ * 만들지 않는다 — 여러 곳에 걸리면 고르는 것은 사람의 일이다.
+ */
+function uniqueModule(labels, present) {
+    const roots = [...new Set(present.map((path) => path.split('/')[0]).filter((root) => Boolean(root)))];
+    for (const label of labels) {
+        const needle = normalize(label);
+        if (needle.length < 3)
+            continue;
+        const hits = roots.filter((root) => normalize(root).includes(needle));
+        if (hits.length !== 1)
+            continue;
+        const root = hits[0];
+        const src = present.find((path) => path === `${root}/src` || path.startsWith(`${root}/src/`));
+        return src ? `${root}/src/**` : `${root}/**`;
+    }
+    return null;
+}
+function acceptanceLines(body) {
+    if (!body)
+        return [];
+    const found = [];
+    let inside = false;
+    for (const line of body.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const bullet = BULLET.exec(line);
+        const item = bullet?.[1] ?? bullet?.[2];
+        if (item) {
+            if (inside)
+                found.push(item.trim());
+            continue;
+        }
+        // 항목이 아닌 줄은 구획 이름이거나 설명이다. 구획 이름이면 여기서 들고 나간다.
+        const label = SECTION_LABEL.exec(line);
+        if (label)
+            inside = ACCEPTANCE_HEADING.test(label[1] ?? '');
+    }
+    return found;
+}

package/dist/core/operator/proceed.d.ts

@@ -1,5 +1,10 @@
 import type { Session } from '../model/entities.ts';
 import type { StateStore } from '../../ports/state-store.ts';
+import type { RepoObservation } from '../../ports/local-repo.ts';
+import type { ChangeSummary } from '../../ports/change-context.ts';
+import type { ContextComment, ResourceSnapshot } from '../../ports/resource-context.ts';
+import type { SessionContractDraft, SessionContractPlan } from './contract-draft.ts';
+import { type WorkStateResult } from './work-state.ts';
 import type { CanonicalDrift, SessionRuntime } from '../runtime/session.ts';
 import { type EscalationLedger } from '../runtime/escalation.ts';
 import { type ExecutionVerdict } from '../runtime/execution-state.ts';
@@ -15,6 +20,57 @@ export type ProceedIntent = {
     sessionId?: string;
     /** 후보가 없을 때 초안에 실어 줄 목표 힌트. 확정이 아니다. */
     goal?: string;
+    /**
+     * 사람이 지목한 작업 항목 (예: 이슈 키). 있으면 후보가 없을 때 **조사부터** 한다 —
+     * 빈 초안을 돌려주는 대신, 실제로 할 일이 있는지를 먼저 판정한다.
+     */
+    workRef?: string;
+};
+/**
+ * 작업 항목 하나를 실제로 조사해 계약까지 잇는 통로 (P0-D).
+ *
+ * 전부 주입이다. Operator 는 adapter 도 policy 도 모르고, 여기 담긴 함수들이 하는 판정을
+ * 다시 계산하지 않는다 — 범위·책임·발급 권한은 `plan` 이 돌려주는 것을 **읽기만** 한다.
+ */
+export type WorkIngress = {
+    /** 작업 항목과 그 둘레를 모은다. 못 모은 것은 'UNAVAILABLE' 로 말한다. */
+    gather: (workRef: string) => Promise<{
+        workItem?: ResourceSnapshot;
+        trackerDone?: boolean;
+        comments?: readonly ContextComment[] | 'UNAVAILABLE';
+        change?: ChangeSummary | 'UNAVAILABLE';
+        dependencies?: readonly {
+            reference: string;
+            state?: string;
+            open?: boolean;
+        }[];
+    }>;
+    /** 저장소 관측. 없으면 'MISSING' 으로 취급되고, 그 상태에서는 어떤 추천도 하지 않는다. */
+    observeRepo?: (query: {
+        refHint: string;
+        paths?: readonly string[];
+    }) => Promise<RepoObservation>;
+    derive: (input: {
+        workRef: string;
+        goal?: string;
+        workItem: ResourceSnapshot;
+        workState: WorkStateResult;
+        repo: RepoObservation | 'MISSING';
+        /** 이미 쓰인 세션 id — 새 id 가 그 위에 겹치지 않게. */
+        existingIds: readonly string[];
+    }) => SessionContractDraft;
+    /** 이미 쓴 세션 id — 회수돼 보관된 것까지. 새 id 가 그 위에 겹치지 않게 한다. */
+    usedIds: () => Promise<readonly string[]>;
+    /** planSessionContract 를 policy·ownership·기존 id 로 감싼 것. */
+    plan: (draft: SessionContractDraft) => Promise<SessionContractPlan>;
+    /** 위임 범위 안에서만 불린다. 발급 경로는 SessionRuntime 하나뿐이다. */
+    issue: (draft: SessionContractDraft) => Promise<{
+        ok: true;
+        sessionId: string;
+    } | {
+        ok: false;
+        detail: string;
+    }>;
 };
 /** 후보 나열용 요약 — 사람이 고를 근거까지 함께 준다. */
 export type SessionCandidate = {
@@ -52,6 +108,24 @@ export type ProceedOutcome = ({
         goal: string;
         doneCriteria: string[];
     };
+    /** 조사에서 도출한 초안 전문. 조사 없이 온 경우엔 없다. */
+    full?: SessionContractDraft;
+    /** planSessionContract 판정 원본. 여기 있는 것을 다시 계산하지 않는다. */
+    plan?: SessionContractPlan;
+    /** 발급이 Controller 것일 때 사람이 그대로 실행할 명령. */
+    forController?: string[];
+}
+/**
+ * 조사해 보니 **세션을 낼 일이 아니다** (P0-B). 이미 구현돼 tracker 만 뒤처졌거나,
+ * 선행 작업·외부 검증에 막혔거나, 결론 요건이 모자란 경우다.
+ *
+ * 아무것도 쓰지 않는다. 파생 뷰이며 저장되지 않는다 — 상태 enum(OM §11.2)을 건드리지 않는다.
+ */
+ | {
+    kind: 'WORK_STATE';
+    workRef: string;
+    result: WorkStateResult;
+    nextAction: string;
 }
 /**
  * 미해소 상신이 실행 가능한 node를 전부 덮었다 (C-13 §6).
@@ -84,6 +158,11 @@ export type OperatorDeps = {
      * 주지 않으면 예전처럼 상태만 보고 간다(기존 호출자 무손상).
      */
     escalations?: EscalationLedger;
+    /**
+     * 작업 항목 통로 (P0-D). 없으면 후보가 없을 때 예전처럼 빈 초안을 제안한다 —
+     * 기존 호출자 무손상.
+     */
+    ingress?: WorkIngress;
     /**
      * 필수다. 모든 진입이 bootstrap/profile.lock 검증을 지난다 — Surface가 어디든.
      * 실 조립은 factory(cli의 createOperator)가 bootstrapGuard로 고정한다.