@asc-agent/runtime 0.1.0

package/dist/core/monitor/relevance.js

@@ -0,0 +1,100 @@
+// Relevance Evaluator — "나를 불렀는가"와 "실제로 내 일인가"를 따로 판정한다 (C-07 §2·§3).
+//
+// 신호(Signal)는 사건에 대한 관찰이고, 관련성(Relevance)은 그 사건과 지금 나·이 프로젝트의
+// 관계다. 둘을 한 층에 두면 태깅 난사와 태깅 누락을 동시에 틀린다:
+//
+//   나를 불렀다  → 내 일이다     ❌ 무관한 곳에 부른 것까지 판단 대기로 올라온다
+//   안 불렀다   → 내 일이 아니다 ❌ 지정이 빠진 실제 내 일을 놓친다
+//
+// 그래서 두 축을 따로 세우고, 낮은 쪽은 버리지 않고 Shadow로 내린다.
+//
+// 판정 근거는 **구조적 사실을 먼저** 본다. 의미 판단(제목이 내 영역 같다)은 보조다 —
+// 그것 하나로 올리기 시작하면 왜 올라왔는지 아무도 설명할 수 없게 된다.
+import { isWithinScopes } from "../policy/scope.js";
+/** 나를 직접 겨눈 신호. 이것들이 explicit targeting의 전부다. */
+const EXPLICIT = new Set([
+    'assigned_to_me',
+    'mentioned_me',
+    'direct_reply',
+    'review_requested',
+]);
+/**
+ * 두 축을 판정한다.
+ *
+ * **숫자를 내지 않는다** (C-07 §3.3). 0.82 같은 값은 사람이 검증할 수 없고, 틀렸을 때 어디가
+ * 틀렸는지도 말해주지 않는다. 대신 근거 문장을 남겨 사람이 뒤집을 수 있게 한다.
+ */
+export function evaluateRelevance(signals, context = {}) {
+    const evidence = [];
+    const explicitSignals = signals.filter((s) => EXPLICIT.has(s));
+    const explicit = explicitSignals.length > 0 ? 'HIGH' : 'LOW';
+    evidence.push(explicit === 'HIGH'
+        ? { kind: 'targeting', detail: `나를 지목한 신호: ${explicitSignals.join(', ')}`, supports: true }
+        : { kind: 'targeting', detail: '나를 지목한 신호가 없다', supports: false });
+    // ① Ownership — 바뀐 경로가 내 영역인가. changed×ownership은 신호가 아니라 근거다 (C-07 §2.4).
+    const myPaths = ownedPaths(context.ownership, context.myRoles);
+    if (context.changedPaths && myPaths.length > 0) {
+        const hits = context.changedPaths.filter((path) => isWithinScopes(path, myPaths));
+        evidence.push(hits.length > 0
+            ? { kind: 'ownership', detail: `내 영역 변경: ${hits.slice(0, 3).join(', ')}`, supports: true }
+            : { kind: 'ownership', detail: '바뀐 경로가 전부 내 영역 밖이다', supports: false });
+    }
+    // ② Work — 지금 돌고 있는 세션의 쓰기 범위를 건드리는가.
+    if (context.changedPaths && context.activeBoundaries?.length) {
+        for (const active of context.activeBoundaries) {
+            const hits = context.changedPaths.filter((path) => isWithinScopes(path, active.paths));
+            if (hits.length > 0) {
+                evidence.push({ kind: 'work', detail: `${active.sessionId} 와 같은 경로를 건드린다`, supports: true });
+            }
+        }
+    }
+    // ③ Contract — 정본 영역을 건드리는가. 신호(open_change_touches_active_canonical)와 같은
+    //    대조를 쓰지만 여기서는 관련성 근거로 다시 든다 — 신호는 "무슨 일이 있었나"이고
+    //    근거는 "그래서 내 일인가"다.
+    if (context.changedPaths && context.canonicalPaths?.length) {
+        const hits = context.changedPaths.filter((path) => isWithinScopes(path, context.canonicalPaths));
+        if (hits.length > 0) {
+            evidence.push({ kind: 'contract', detail: `정본 영역 변경: ${hits.slice(0, 3).join(', ')}`, supports: true });
+        }
+    }
+    if (signals.includes('active_canonical_changed')) {
+        evidence.push({ kind: 'contract', detail: '정본 baseline이 실제로 움직였다', supports: true });
+    }
+    // ④ Participation — 내가 이미 들어가 있던 자리인가.
+    if (context.participated) {
+        evidence.push({ kind: 'participation', detail: '전에 이 스레드에 참여했다', supports: true });
+    }
+    else if (signals.includes('my_pr_reviewed')) {
+        evidence.push({ kind: 'participation', detail: '내가 만든 변경에 대한 반응이다', supports: true });
+    }
+    // ⑤ Semantic — 보조. 이것 하나로는 올리지 않는다.
+    if (context.semanticHint) {
+        evidence.push({ kind: 'semantic', detail: context.semanticHint, supports: true });
+    }
+    const structural = evidence.filter((e) => e.supports && e.kind !== 'targeting' && e.kind !== 'semantic');
+    const actual = structural.length > 0 ? 'HIGH' : 'LOW';
+    return {
+        explicit,
+        actual,
+        evidence,
+        // 실제로 관련되면 올린다. 관련 근거가 없으면 나를 불렀더라도 Shadow로 내린다 —
+        // 다만 버리지 않는다 (C-07 §5).
+        disposition: actual === 'HIGH' ? 'INBOX' : 'SHADOW',
+    };
+}
+/** 이 사람이 맡은 역할들의 쓰기 영역. 역할 선언이 없으면 빈 목록이다 — 추론하지 않는다. */
+function ownedPaths(map, roles) {
+    if (!map || !roles?.length)
+        return [];
+    return roles.flatMap((role) => map[role]?.paths ?? []);
+}
+/** 사람이 읽는 근거 블록. 근거 없이 결론만 보여주지 않는다. */
+export function renderRelevance(relevance) {
+    const lines = [`Relevance: ${relevance.actual} (지목 ${relevance.explicit})`];
+    for (const item of relevance.evidence)
+        lines.push(`  ${item.supports ? '+' : '-'} ${item.detail}`);
+    if (relevance.disposition === 'SHADOW') {
+        lines.push('  → Shadow Watch (숨김. 변화가 생기면 다시 본다)');
+    }
+    return lines;
+}

package/dist/core/monitor/signals.d.ts

@@ -0,0 +1,59 @@
+import type { EventType, Priority } from '../model/entities.ts';
+import type { RawEvent } from '../../ports/event-source.ts';
+export declare const GENERIC_SIGNALS: readonly ["assigned_to_me", "mentioned_me", "direct_reply", "review_requested", "my_pr_reviewed", "participated_thread_changed", "active_canonical_changed", "open_change_touches_active_canonical", "priority_labels", "project_specific_signal"];
+export type GenericSignal = (typeof GENERIC_SIGNALS)[number];
+/**
+ * 신호를 판정하는 데 필요한 프로젝트별 값. 선언형이어야 Profile(B-10)이 그대로 채울 수 있다 —
+ * 여기에 함수를 받기 시작하면 설정 파일로는 표현할 수 없는 물건이 된다.
+ */
+export type MonitorConfig = {
+    /** "나"로 인정할 계정들. 개인 값이므로 User Override 몫이다 (OM §4.4). */
+    identities?: readonly string[];
+    /**
+     * provider가 주는 사유 → 신호. Core에 기본값을 두지 않는다 — 어느 provider의 `mention`이든
+     * 다른 곳의 무엇이든 그건 provider의 어휘이고, 여기 박아 두면 Core가 특정 provider를
+     * 아는 물건이 된다. 매핑은 Adapter가 내놓고 Profile이 고른다.
+     */
+    reasonSignals?: Readonly<Record<string, GenericSignal>>;
+    /** 라벨 → 우선순위. */
+    priorityLabels?: Readonly<Record<string, Priority>>;
+    /** 붙어 있으면 한 단계 올린다. */
+    escalationLabels?: readonly string[];
+    /** 신호별 기본 우선순위. */
+    signalPriority?: Partial<Record<GenericSignal, Priority>>;
+    /** 이 신호 중 하나라도 있으면 사람의 판단 대기함에 올린다. 비우면 신호가 있는 것 전부. */
+    inboxSignals?: readonly GenericSignal[];
+};
+export type Classification = {
+    signals: GenericSignal[];
+    type: EventType;
+    priority: Priority;
+    inboxCandidate: boolean;
+};
+/**
+ * 신호를 세우는 데 필요한 **관찰된 사실**. Config와 나누는 이유는 성격이 다르기 때문이다 —
+ * Config는 프로젝트가 미리 적어 두는 선언이고, 이쪽은 이번 사건을 보고 알게 된 것이다.
+ * 여기에 함수를 받지 않는 것도 같은 이유다 (설정 파일로 표현할 수 없는 물건이 되지 않게).
+ *
+ * 전부 optional이다 — 모르면 그 신호를 세우지 않는다. 모르는 것을 false로 적으면
+ * "안 건드렸다"는 틀린 판정이 된다.
+ */
+export type SignalContext = {
+    /**
+     * 나에게 배정됐는가. 목록 조회로 알게 되는 사실이라 알림 사유와 별개다 —
+     * 지정이 알림으로 오지 않는 경우가 정확히 회수 경로가 필요한 이유다.
+     */
+    assignedToMe?: boolean;
+    /** 내 글에 달린 응답인가. */
+    replyToMe?: boolean;
+    /** 정본 baseline이 실제로 움직였는가 — actual drift. */
+    canonicalChanged?: boolean;
+    /** 이번 변경이 건드린 실제 경로. */
+    changedPaths?: readonly string[];
+    /** 정본이 사는 경로. 위와 겹치면 potential drift다. */
+    canonicalPaths?: readonly string[];
+};
+/** 이 이벤트에 어떤 신호가 걸리는가. 순서는 판정에 영향이 없다. */
+export declare function detectSignals(event: RawEvent, config: MonitorConfig, context?: SignalContext): GenericSignal[];
+/** 신호를 유형·우선순위·수신함 여부로 옮긴다. Phase A의 마지막 단계다. */
+export declare function classify(event: RawEvent, config: MonitorConfig, context?: SignalContext): Classification;

package/dist/core/monitor/signals.js

@@ -0,0 +1,105 @@
+// Generic Signal — Core가 아는 신호의 전부 (OM §10.6).
+//
+// 여기에 계정 이름도, 라벨 이름도, 저장소 이름도 없다. "나에게 배정됐다"는 개념은 알지만
+// 누가 나인지는 모르고, "우선순위 라벨"이라는 개념은 알지만 어떤 이름의 라벨인지는 모른다.
+// 실제 값은 Profile과 User Override가 채운다 — 그래야 같은 Core가 다른 프로젝트에 붙는다.
+import { isWithinScopes } from "../policy/scope.js";
+export const GENERIC_SIGNALS = [
+    'assigned_to_me',
+    'mentioned_me',
+    'direct_reply',
+    'review_requested',
+    'my_pr_reviewed',
+    'participated_thread_changed',
+    'active_canonical_changed',
+    'open_change_touches_active_canonical',
+    'priority_labels',
+    'project_specific_signal',
+];
+const DEFAULT_SIGNAL_PRIORITY = {
+    assigned_to_me: 'P0',
+    mentioned_me: 'P0',
+    direct_reply: 'P0',
+    review_requested: 'P1',
+    my_pr_reviewed: 'P1',
+    participated_thread_changed: 'P1',
+    active_canonical_changed: 'P1',
+    open_change_touches_active_canonical: 'P2',
+    priority_labels: 'P1',
+    project_specific_signal: 'P2',
+};
+/** 답을 해야 하는 신호. 나머지는 알아두면 되는 것이다 (OM §10.3). */
+const ACTIONABLE = new Set(['mentioned_me', 'direct_reply', 'review_requested']);
+const WORK = new Set(['assigned_to_me']);
+const RANK = ['P0', 'P1', 'P2'];
+const higher = (a, b) => (RANK.indexOf(a) <= RANK.indexOf(b) ? a : b);
+const raise = (p) => RANK[Math.max(0, RANK.indexOf(p) - 1)];
+function mentionsMe(text, identities) {
+    if (!text)
+        return false;
+    return identities.some((id) => text.includes(`@${id.replace(/^@/, '')}`));
+}
+/** 이 이벤트에 어떤 신호가 걸리는가. 순서는 판정에 영향이 없다. */
+export function detectSignals(event, config, context = {}) {
+    const identities = config.identities ?? [];
+    const raw = (event.raw ?? {});
+    const signals = new Set();
+    if (raw.reason) {
+        const mapped = config.reasonSignals?.[raw.reason];
+        if (mapped)
+            signals.add(mapped);
+    }
+    // 본문에 내 이름이 불렸다. 알림이 오지 않는 경로(참여하지 않은 스레드)에서도 잡힌다.
+    if (mentionsMe(raw.body, identities))
+        signals.add('mentioned_me');
+    const labels = event.hints?.labels ?? [];
+    if (labels.some((label) => config.priorityLabels?.[label] !== undefined))
+        signals.add('priority_labels');
+    if (context.assignedToMe)
+        signals.add('assigned_to_me');
+    // 내 글에 달린 응답. provider의 알림 사유로는 mention과 구분되지 않는 경우가 많아
+    // 관찰된 사실로 받는다.
+    if (context.replyToMe)
+        signals.add('direct_reply');
+    // 정본이 **이미** 움직인 것과, 열린 변경이 정본 영역을 **건드리는** 것은 다른 사건이다
+    // (C-07 §2.4). 둘을 합치면 "바뀌었다"와 "바뀔 수 있다"를 구분할 수 없게 된다.
+    if (context.canonicalChanged)
+        signals.add('active_canonical_changed');
+    if (context.changedPaths?.length &&
+        context.canonicalPaths?.length &&
+        context.changedPaths.some((path) => isWithinScopes(path, context.canonicalPaths))) {
+        signals.add('open_change_touches_active_canonical');
+    }
+    // 내가 쓴 글은 나에게 알릴 일이 아니다 — 다른 신호가 없다면 조용히 넘긴다.
+    const authors = event.hints?.actors ?? [];
+    const mine = authors.length > 0 && authors.every((a) => identities.includes(a));
+    if (mine && signals.size === 0)
+        return [];
+    return [...signals];
+}
+/** 신호를 유형·우선순위·수신함 여부로 옮긴다. Phase A의 마지막 단계다. */
+export function classify(event, config, context = {}) {
+    const signals = detectSignals(event, config, context);
+    const type = signals.some((s) => WORK.has(s))
+        ? 'work'
+        : signals.some((s) => ACTIONABLE.has(s))
+            ? 'actionable'
+            : 'informational';
+    let priority = 'P2';
+    for (const signal of signals) {
+        priority = higher(priority, config.signalPriority?.[signal] ?? DEFAULT_SIGNAL_PRIORITY[signal]);
+    }
+    for (const label of event.hints?.labels ?? []) {
+        const mapped = config.priorityLabels?.[label];
+        if (mapped)
+            priority = higher(priority, mapped);
+    }
+    if ((event.hints?.labels ?? []).some((label) => (config.escalationLabels ?? []).includes(label))) {
+        priority = raise(priority);
+    }
+    // provider가 힌트를 줬다면 참고는 하되, 올리는 쪽으로만 쓴다
+    if (event.hints?.priority)
+        priority = higher(priority, event.hints.priority);
+    const inboxCandidate = signals.length > 0 && (config.inboxSignals === undefined || signals.some((s) => config.inboxSignals.includes(s)));
+    return { signals, type, priority, inboxCandidate };
+}

package/dist/core/operator/local-operator.d.ts

@@ -0,0 +1,60 @@
+import type { ScmPort } from '../../ports/scm.ts';
+import type { HistoryEntry, StateStore } from '../../ports/state-store.ts';
+import type { DecisionSummary, DecisionView } from '../view/decision-view.ts';
+export type ListOptions = {
+    /** true면 처분된 것까지 전부 (기본은 판단 대기만). */
+    all?: boolean;
+    priority?: 'P0' | 'P1' | 'P2';
+    limit?: number;
+};
+export type GetOutcome = {
+    ok: true;
+    view: DecisionView;
+} | {
+    ok: false;
+    reason: 'NOT_FOUND';
+    requestId: string;
+};
+/**
+ * 참조가 하나로 좁혀지지 않을 때의 결과. Agent가 임의로 하나를 고르지 않도록
+ * 후보를 그대로 돌려준다 (C-01 §11).
+ */
+export type ResolveOutcome = {
+    kind: 'resolved';
+    view: DecisionView;
+} | {
+    kind: 'ambiguous';
+    candidates: DecisionSummary[];
+} | {
+    kind: 'none';
+};
+export type OperatorDeps = {
+    store: StateStore;
+    /** 없어도 동작한다 — 정본·스레드 확인만 건너뛴다. */
+    scm?: ScmPort;
+    /** 테스트에서 시각을 고정하기 위한 주입점. */
+    now?: () => string;
+};
+export declare class LocalOperator {
+    #private;
+    constructor(deps: OperatorDeps);
+    /** 최근 감지 순. 목록에도 freshness를 붙여 이미 결정된 것을 눈에 띄게 한다. */
+    list(options?: ListOptions): Promise<DecisionSummary[]>;
+    /** 하나를 지목해 전체 보고서를 만든다 — stored와 current를 함께 담는다. */
+    get(requestId: string): Promise<GetOutcome>;
+    /**
+     * "방금 온 알림 보여줘" — request_id 없이 최근 것을 찾는다.
+     * 후보가 여럿이면 하나를 고르지 않고 그대로 돌려준다. 잘못 고른 요청을 승인 화면까지
+     * 끌고 가는 것보다 한 번 더 묻는 편이 싸다.
+     */
+    resolveLatest(options?: ListOptions): Promise<ResolveOutcome>;
+    /**
+     * 이 요청이 지금 상태가 된 경위 (C-05 §3.2 trace).
+     *
+     * 새 저장 구조를 만들지 않는다 — depth는 "얼마나 읽을 것인가"의 계약이지 새 데이터가
+     * 아니고, 감지와 최종 처분의 이력은 이미 History Log에 있다 (OM §11.2).
+     *
+     * 여기도 읽기뿐이다. 경위를 아무리 깊게 읽어도 결정 제출 경로는 열리지 않는다 (C-01 §5).
+     */
+    trace(requestId: string, limit?: number): Promise<HistoryEntry[]>;
+}

package/dist/core/operator/local-operator.js

@@ -0,0 +1,82 @@
+// Local Operator Interface — 로컬 작업환경이 ASC 요청을 조회하는 표면 (C-01 §4).
+//
+// Core는 어떤 도구가 이걸 부르는지 모른다. CLI든 MCP든 IDE 확장이든 전부 소비자일 뿐이고,
+// 제품 이름이 이 파일에 들어오는 순간 계약이 깨진다.
+//
+// 여기 있는 것은 읽기뿐이다. 결정 제출은 사람의 명시적 의사표현을 받은 뒤에만 일어나므로
+// 별도 경로(B-06)로 나간다 — Agent가 조회하다가 이어서 승인해버릴 수 있는 문을 만들지 않는다 (C-01 §5).
+import { assembleView, assess, buildOverlay, summarize } from "../view/build-view.js";
+/** 아직 사람의 판단을 기다리는 상태. 목록의 기본 필터다. */
+const PENDING = new Set(['AWAITING_APPROVAL', 'APPROVED']);
+export class LocalOperator {
+    #store;
+    #scm;
+    #now;
+    constructor(deps) {
+        this.#store = deps.store;
+        this.#scm = deps.scm;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    /** 최근 감지 순. 목록에도 freshness를 붙여 이미 결정된 것을 눈에 띄게 한다. */
+    async list(options = {}) {
+        const requests = await this.#store.list('request');
+        const filtered = requests
+            .filter((r) => options.all || PENDING.has(r.status))
+            .filter((r) => !options.priority || r.priority === options.priority)
+            .sort((a, b) => b.detectedAt.localeCompare(a.detectedAt))
+            .slice(0, options.limit ?? requests.length);
+        const summaries = [];
+        for (const request of filtered)
+            summaries.push(summarize(request, await this.#freshness(request)));
+        return summaries;
+    }
+    /** 하나를 지목해 전체 보고서를 만든다 — stored와 current를 함께 담는다. */
+    async get(requestId) {
+        const request = await this.#store.get('request', requestId);
+        if (!request)
+            return { ok: false, reason: 'NOT_FOUND', requestId };
+        return { ok: true, view: await this.#view(request) };
+    }
+    /**
+     * "방금 온 알림 보여줘" — request_id 없이 최근 것을 찾는다.
+     * 후보가 여럿이면 하나를 고르지 않고 그대로 돌려준다. 잘못 고른 요청을 승인 화면까지
+     * 끌고 가는 것보다 한 번 더 묻는 편이 싸다.
+     */
+    async resolveLatest(options = {}) {
+        const candidates = await this.list({ ...options, limit: undefined });
+        if (candidates.length === 0)
+            return { kind: 'none' };
+        if (candidates.length > 1)
+            return { kind: 'ambiguous', candidates };
+        const outcome = await this.get(candidates[0].requestId);
+        return outcome.ok ? { kind: 'resolved', view: outcome.view } : { kind: 'none' };
+    }
+    /**
+     * 이 요청이 지금 상태가 된 경위 (C-05 §3.2 trace).
+     *
+     * 새 저장 구조를 만들지 않는다 — depth는 "얼마나 읽을 것인가"의 계약이지 새 데이터가
+     * 아니고, 감지와 최종 처분의 이력은 이미 History Log에 있다 (OM §11.2).
+     *
+     * 여기도 읽기뿐이다. 경위를 아무리 깊게 읽어도 결정 제출 경로는 열리지 않는다 (C-01 §5).
+     */
+    async trace(requestId, limit) {
+        const entries = await this.#store.readHistory(limit);
+        return entries.filter((entry) => entry.ref === requestId);
+    }
+    async #view(request) {
+        const overlay = await buildOverlay(request, {
+            control: await this.#store.getControlState(),
+            observedAt: this.#now(),
+            ...(this.#scm ? { scm: this.#scm } : {}),
+        });
+        return assembleView(request, await assess(request, overlay, this.#scm), overlay);
+    }
+    async #freshness(request) {
+        const overlay = await buildOverlay(request, {
+            control: await this.#store.getControlState(),
+            observedAt: this.#now(),
+            ...(this.#scm ? { scm: this.#scm } : {}),
+        });
+        return (await assess(request, overlay, this.#scm)).freshness;
+    }
+}

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

@@ -0,0 +1,60 @@
+import { type AuthorityLookup, type OwnershipMap } from '../policy/ownership.ts';
+import type { ResolvedPolicy, RoleName } from '../policy/policy.ts';
+/** 무엇과 대조하는가. role은 최대 범위, session은 실제 계약 — 후자가 더 좁을 수 있다. */
+export type PreflightTarget = {
+    kind: 'role';
+    role: RoleName;
+    maxScope: readonly string[] | undefined;
+} | {
+    kind: 'session';
+    sessionId: string;
+    role?: RoleName;
+    writeBoundary: readonly string[];
+    /** 책임 축 (C-04 §2). 선언하지 않은 세션에서는 이 축을 판정하지 않는다. */
+    owner?: string;
+    decisionDomains?: readonly string[];
+    decisionAuthority?: Readonly<Record<string, string>>;
+};
+export type PathVerdict = {
+    path: string;
+    verdict: 'OK';
+}
+/** 문법 밖 경로. 통과시키지 않는다 — 판정할 수 없는 것은 통과가 아니다. */
+ | {
+    path: string;
+    verdict: 'INVALID_SCOPE';
+} | {
+    path: string;
+    verdict: 'BOUNDARY_MISMATCH';
+}
+/** 쓰기 범위 안이지만 owner의 영역 밖이다 — 남의 파트 산출물을 만들고 있다. */
+ | {
+    path: string;
+    verdict: 'OWNERSHIP_MISMATCH';
+};
+export type PreflightResult = {
+    target: PreflightTarget;
+    verdicts: PathVerdict[];
+    mismatches: PathVerdict[];
+    /** 사람이 읽을 대안. 문자열뿐이다 — 실행 가능한 명령을 자동으로 태우지 않는다. */
+    suggestions: string[];
+    /**
+     * 주인이 정해지지 않은 결정 영역. 경로 축(PathVerdict)과 다른 축이라 따로 든다 —
+     * 결정은 파일에 붙지 않으므로 경로별 판정에 섞을 수 없다.
+     */
+    authorityGaps: {
+        domain: string;
+        lookup: AuthorityLookup;
+    }[];
+    /** 판정이 성립하지 않은 이유. 있으면 결과를 "통과"로 읽으면 안 된다. */
+    undecidable?: string;
+};
+export type PreflightInput = {
+    paths: readonly string[];
+    target: PreflightTarget;
+    /** role 후보 제안용. 없으면 후보를 내지 않는다. */
+    policy?: ResolvedPolicy;
+    /** Profile이 선언한 책임 지도 (C-04 §6). 없으면 책임 축은 판정 불성립이다. */
+    ownership?: OwnershipMap;
+};
+export declare function preflight(input: PreflightInput): PreflightResult;

package/dist/core/operator/preflight.js

@@ -0,0 +1,139 @@
+// Boundary Preflight — 다른 role에게 일을 넘기기 전에 경로를 맞춰 본다 (B-19).
+//
+// 근거 사건(B-16 T015): planner가 tasks.md에 산출 경로 `specs/.../quickstart.md`를 적었는데
+// 그 일을 할 implementer의 쓰기 범위는 `web-frontend/**`였다. 불일치는 실행 단계에서야
+// 드러났고, 해소하는 데 세션을 하나 더 발급해야 했다. 대조 자체는 1초면 되는데 그걸
+// 나중에 한 것이 비용이었다.
+//
+// 이 모듈이 하는 일과 하지 않는 일:
+//   한다   — 경로가 대상 범위 안에 드는지 판정하고, 어긋나면 대안을 문장으로 제시
+//   안 한다 — 범위 확장, role 변경, 세션 발급. 판정은 여기서, 결정은 Controller가.
+//
+// 판정 로직은 새로 만들지 않는다. scope.ts의 패턴 대 패턴 판정을 그대로 쓴다 —
+// policy.evaluate()를 쓰지 않는 이유는 그쪽이 단수 path + 경로 대 패턴이라
+// `specs/**` 같은 패턴 입력을 오판하기 때문이다.
+import { lookupAuthority } from "../policy/ownership.js";
+import { isWithinScopes, parseScope } from "../policy/scope.js";
+export function preflight(input) {
+    const { paths, target, policy, ownership } = input;
+    const boundary = target.kind === 'role' ? target.maxScope : target.writeBoundary;
+    // 정책에 role이 선언돼 있지 않으면 최대 범위를 모른다. 모르는 것을 통과로 만들지 않는다 —
+    // Session issue의 SCOPE_ESCALATION 검사도 같은 자리에서 검사를 건너뛰므로(session.ts),
+    // preflight까지 조용히 통과시키면 두 곳 다 아무 말이 없게 된다.
+    if (boundary === undefined) {
+        return {
+            target,
+            verdicts: [],
+            mismatches: [],
+            suggestions: [],
+            authorityGaps: [],
+            undecidable: target.kind === 'role'
+                ? `Profile에 '${target.role}' 역할의 쓰기 범위가 선언돼 있지 않다 — 대조할 기준이 없다`
+                : `${target.sessionId} 의 쓰기 범위를 읽지 못했다`,
+        };
+    }
+    // owner의 영역. 선언한 세션에서만 쓴다 — role 대조에는 owner가 없다.
+    const ownerPaths = target.kind === 'session' && target.owner ? ownership?.[target.owner]?.paths : undefined;
+    const verdicts = paths.map((path) => {
+        if (parseScope(path) === null)
+            return { path, verdict: 'INVALID_SCOPE' };
+        if (!isWithinScopes(path, boundary))
+            return { path, verdict: 'BOUNDARY_MISMATCH' };
+        // 쓰기 범위는 "이 계약이 어디까지 쓸 수 있는가"이고, 여기는 "그게 누구 영역인가"다.
+        // 둘 다 통과해야 남의 파트를 대신 만들고 있지 않다고 말할 수 있다.
+        if (ownerPaths && ownerPaths.length > 0 && !isWithinScopes(path, ownerPaths)) {
+            return { path, verdict: 'OWNERSHIP_MISMATCH' };
+        }
+        return { path, verdict: 'OK' };
+    });
+    const mismatches = verdicts.filter((v) => v.verdict !== 'OK');
+    const authorityGaps = findAuthorityGaps(target, ownership);
+    const result = {
+        target,
+        verdicts,
+        mismatches,
+        authorityGaps,
+        suggestions: mismatches.length === 0 && authorityGaps.length === 0
+            ? []
+            : suggest(paths, verdicts, target, boundary, policy, authorityGaps),
+    };
+    // 책임을 물었는데 지도가 없다. 답이 없는 것과 "괜찮다"는 것을 구분한다.
+    if (target.kind === 'session' && !ownership && (target.owner || target.decisionDomains?.length)) {
+        result.undecidable = 'Profile에 책임 지도(ownership)가 선언돼 있지 않다 — 책임 축을 대조할 기준이 없다';
+    }
+    return result;
+}
+/** 주인이 하나로 정해지지 않은 결정 영역만 골라낸다. 고르지는 않는다. */
+function findAuthorityGaps(target, ownership) {
+    if (target.kind !== 'session')
+        return [];
+    const gaps = [];
+    for (const domain of target.decisionDomains ?? []) {
+        if (target.decisionAuthority?.[domain])
+            continue;
+        const lookup = lookupAuthority(ownership, domain);
+        if (lookup.kind !== 'RESOLVED')
+            gaps.push({ domain, lookup });
+    }
+    return gaps;
+}
+function suggest(paths, verdicts, target, boundary, policy, authorityGaps) {
+    const out = [];
+    for (const gap of authorityGaps) {
+        out.push(gap.lookup.kind === 'AMBIGUOUS'
+            ? `'${gap.domain}' 의 결정권자가 갈려 있다 (${gap.lookup.candidates.join(', ')}) — 발급 전에 하나로 정하라.`
+            : `'${gap.domain}' 의 결정권자가 선언되지 않았다 — Profile ownership 에 적거나 세션 계약에 명시하라.`);
+    }
+    if (authorityGaps.length > 0) {
+        out.push('결정권자가 없는 채로 cross-part를 시작하면 답이 Agent 사이를 돈다. 먼저 정한다.');
+    }
+    if (verdicts.some((v) => v.verdict === 'OWNERSHIP_MISMATCH') && target.kind === 'session') {
+        out.push(`쓰기 범위 안이지만 '${target.owner}' 의 영역 밖인 경로가 있다 — 남의 파트 산출물이라면 ` +
+            '그 파트가 만들고, 이 세션은 필요한 것을 질의로 받는다.');
+    }
+    if (verdicts.some((v) => v.verdict === 'INVALID_SCOPE')) {
+        out.push('문법 밖 경로를 먼저 고쳐라 — 허용 형태는 `**`, `p/**`, `p/*`, 정확한 경로다.');
+    }
+    // 쓰기 범위가 비면 경로를 옮기는 게 아니라 대상 선택이 잘못된 것이다.
+    // 다만 "이 역할은 파일을 만들지 않는다"고 단정하지 않는다 — 그건 역할의 본질이 아니라
+    // 지금 정책이 그렇게 정해 둔 상태다. Profile에 값만 있고 설명이 없어 여기서 말해 준다.
+    if (boundary.length === 0) {
+        out.push(target.kind === 'role'
+            ? `'${target.role}' 에게 현재 허용된 쓰기 범위가 없다 — 지금 정책에서는 이 역할로 파일을 만들 수 없다. 산출물이 필요하면 다른 역할이 맡거나 정책을 바꿔야 한다.`
+            : `${target.sessionId} 에 현재 허용된 쓰기 범위가 없다 — 이 계약으로는 어떤 파일도 만들 수 없다.`);
+    }
+    const candidates = rolesCovering(paths, policy, target);
+    if (candidates.length > 0) {
+        out.push(`산출 경로 전체를 최대 범위 안에 두는 역할: ${candidates.join(', ')}. ` +
+            '다만 이는 **역할의 최대 범위** 기준이다 — 실제 세션의 쓰기 범위는 발급 시 더 좁게 정해질 수 있으므로, ' +
+            '발급 후 `asc preflight --session <S-ID>` 로 다시 확인하라.');
+    }
+    else if (policy) {
+        out.push('이 산출 경로들을 한 역할이 통째로 맡을 수 없다 — 경로별로 세션을 나누거나, ' +
+            '산출 경로를 수행 역할의 범위 안으로 옮겨라.');
+    }
+    out.push('세션을 나눈다 — 범위가 다른 산출물은 각자의 계약으로 발급한다.');
+    out.push('산출 경로를 옮긴다 — 수행 역할의 범위 안에 두면 세션을 늘리지 않아도 된다.');
+    out.push('쓰기 범위를 넓혀 해소하지 않는다. 권한 확대는 Controller의 명시적 결정이다.');
+    return out;
+}
+/**
+ * 경로 **전부**를 최대 범위에 담는 역할만 후보다. 일부만 담는 역할을 권하면
+ * 그 역할로 바꿔도 다시 갈라져 같은 사건이 반복된다.
+ */
+function rolesCovering(paths, policy, target) {
+    if (!policy)
+        return [];
+    const valid = paths.filter((p) => parseScope(p) !== null);
+    if (valid.length === 0)
+        return [];
+    return Object.entries(policy.roleScopes)
+        .filter(([role, scope]) => {
+        if (target.kind === 'role' && role === target.role)
+            return false; // 지금 어긋난 그 역할
+        if (!scope || scope.length === 0)
+            return false;
+        return valid.every((p) => isWithinScopes(p, scope));
+    })
+        .map(([role]) => role);
+}