@asc-agent/runtime 0.1.0

package/dist/adapters/jam/event-source.js

@@ -0,0 +1,65 @@
+// JAM Incremental EventSource — 빠른 변경 회수 (C-07 §1.1).
+//
+// **푸시가 있다고 말하지 않는다.** JAM에는 webhook도 알림 스트림도 없다. 여기서 하는 것은
+// `updated >= watermark` 조회이며, 그것은 C-07 §1.1이 Delta에 명시적으로 포함한 형태다
+// ("webhook / incremental polling / provider notification / **updated-since**").
+//
+// 그래서 이 파일이 여는 것은 `observe.delta` 이지 push가 아니다. 둘을 같은 말로 쓰면
+// "실시간이다"라는 잘못된 기대가 생기고, 그 기대 위에서 사람들이 감시 주기를 늘린다.
+//
+// 시각 정밀도가 핵심 위험이다. JAM의 `updated` 는 분 단위라, 같은 분 안에서 일어난
+// 변경은 watermark를 그 값으로 올리는 순간 영영 안 보인다. **누락이 중복보다 위험하므로**
+// 겹쳐 읽는다 — 중복은 dedupe가 거르지만 누락은 아무도 모른다.
+/**
+ * 분 단위 정밀도를 덮는 겹침. JamInventory의 JQL 변환이 쓰는 값과 같은 이유로 60초다 —
+ * 한쪽만 겹치면 겹치지 않은 쪽이 조용히 놓친다.
+ */
+export const OVERLAP_MS = 60_000;
+export class JamEventSource {
+    id;
+    #inventory;
+    #now;
+    constructor(deps) {
+        this.id = deps.id ?? 'jam-updated';
+        this.#inventory = deps.inventory;
+        this.#now = deps.now ?? (() => new Date().toISOString());
+    }
+    /** "지금부터 보겠다". 처음 붙인 프로젝트의 과거를 통째로 긁으면 그 자체가 잡음이다. */
+    cursorFrom(since) {
+        return since;
+    }
+    /**
+     * cursor 이후로 바뀐 것을 사건으로 흘린다.
+     *
+     * **cursor는 성공한 회차에만 전진한다.** 목록을 끝까지 못 봤으면(`complete=false`)
+     * 그 회차의 최대 시각으로 올리지 않는다 — 못 본 구간을 본 것으로 표시하는 셈이 된다
+     * (C-07 §1.5).
+     */
+    async drain(cursor) {
+        const since = cursor ?? undefined;
+        const page = await this.#inventory.enumerate(since ? { updatedSince: overlapped(since) } : {});
+        const events = page.items.map((item) => ({
+            // 같은 항목이 같은 시각으로 다시 와도 같은 키다 — 중복은 여기서 이미 접힌다
+            eventKey: `jam:${item.reference}:${item.revisionMarker}`,
+            detectedAt: item.updatedAt,
+            reference: item.reference,
+            hints: {
+                ...(item.assignees ? { actors: item.assignees } : {}),
+                ...(item.labels ? { labels: item.labels } : {}),
+            },
+            raw: { kind: 'work_item', state: item.state, title: item.title },
+        }));
+        if (!page.complete) {
+            // 못 본 구간이 있다. cursor를 그대로 두어 다음 회차가 같은 자리에서 다시 본다.
+            return { events, cursor: cursor ?? null, hasMore: true };
+        }
+        const latest = page.items.reduce((max, item) => (max === undefined || item.updatedAt > max ? item.updatedAt : max), undefined);
+        // 이번에 아무것도 없었으면 시계를 옮기지 않는다 — 옮길 근거가 없다.
+        return { events, cursor: latest ?? cursor ?? this.#now(), hasMore: false };
+    }
+}
+/** watermark를 뒤로 물린다. 분 단위 반올림으로 같은 분의 변경을 놓치지 않기 위해서다. */
+function overlapped(since) {
+    const at = new Date(since).getTime();
+    return Number.isNaN(at) ? since : new Date(at - OVERLAP_MS).toISOString();
+}

package/dist/adapters/jam/mcp-client.d.ts

@@ -0,0 +1,50 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+export type McpRequest = {
+    method: string;
+    params?: unknown;
+};
+export type McpFailure = {
+    kind: 'SPAWN_FAILED' | 'TIMEOUT' | 'PROCESS_EXITED' | 'PROTOCOL_ERROR' | 'TOOL_ERROR';
+    detail: string;
+};
+export type McpResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+} & McpFailure;
+/** MCP tool 하나의 응답. JAM은 결과를 text content 한 덩어리에 담아 준다. */
+export type ToolResponse = {
+    content?: {
+        type: string;
+        text?: string;
+    }[];
+    isError?: boolean;
+};
+export type JamMcpClientDeps = {
+    /** JAM 실행 경로. 값을 문서·Profile·repo에 남기지 않는다 — 환경에서만 온다. */
+    command: string;
+    args?: readonly string[];
+    /** JAM은 프로젝트 선언(.jira-agent/project.yaml)이 있는 디렉터리에서 떠야 한다. */
+    cwd?: string;
+    /** 한 요청이 이보다 오래 걸리면 끊는다. 매달린 자식이 회차를 통째로 잡아먹지 않게. */
+    timeoutMs?: number;
+    /**
+     * 프로세스를 띄우는 통로. 테스트가 실제 자식을 띄우지 않기 위한 주입점이다 —
+     * 실 프로세스에 기대는 테스트는 남의 사정으로 깨진다.
+     */
+    spawnProcess?: () => ChildProcessWithoutNullStreams;
+};
+export declare class JamMcpClient {
+    #private;
+    constructor(deps: JamMcpClientDeps);
+    /** 띄우고 악수까지. 여기서 실패하면 tool 호출을 시도조차 하지 않는다. */
+    start(): Promise<McpResult<{
+        name: string;
+        version: string;
+    }>>;
+    /** tool 하나를 부르고 text content를 JSON으로 푼다. */
+    callTool<T>(name: string, args: Record<string, unknown>): Promise<McpResult<T>>;
+    /** 자식을 정리한다. 여러 번 불러도 안전하다. */
+    stop(): Promise<void>;
+}

package/dist/adapters/jam/mcp-client.js

@@ -0,0 +1,218 @@
+// stdio MCP 최소 클라이언트.
+//
+// SDK를 들이지 않는다 (C-09 §8). 필요한 것은 줄 단위 JSON-RPC 왕복 하나뿐이고, 그것 때문에
+// 의존성을 늘리면 "외부 의존이 Core로 전파되지 않는다"는 목표가 adapter 층에서부터 흔들린다.
+//
+// 프로토콜은 실측으로 확인했다 — Content-Length 프레이밍이 아니라 **개행 구분 JSON**이고,
+// 서버는 stderr에 자기 로그를 쓴다.
+//
+// 지켜야 할 것 둘:
+//   stderr를 프로토콜로 읽지 않는다 — 진단용으로만 쓰고, 그것도 길이를 제한한다
+//   자격 값을 절대 기록하지 않는다 — 이 파일은 토큰을 받지도, 보지도, 남기지도 않는다
+import { spawn } from 'node:child_process';
+const PROTOCOL_VERSION = '2024-11-05';
+/** 진단으로 남길 stderr 최대 길이. 무한히 모으면 그 자체가 새는 곳이 된다. */
+const STDERR_KEEP = 2000;
+export class JamMcpClient {
+    #deps;
+    #child = null;
+    #pending = new Map();
+    #buffer = '';
+    #stderr = '';
+    #nextId = 1;
+    #exited = null;
+    #ready = false;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /** 띄우고 악수까지. 여기서 실패하면 tool 호출을 시도조차 하지 않는다. */
+    async start() {
+        if (this.#ready && this.#child)
+            return { ok: true, value: { name: '', version: '' } };
+        try {
+            this.#child = this.#deps.spawnProcess
+                ? this.#deps.spawnProcess()
+                : spawn(this.#deps.command, [...(this.#deps.args ?? [])], {
+                    stdio: ['pipe', 'pipe', 'pipe'],
+                    ...(this.#deps.cwd ? { cwd: this.#deps.cwd } : {}),
+                });
+        }
+        catch (error) {
+            return { ok: false, kind: 'SPAWN_FAILED', detail: String(error) };
+        }
+        const child = this.#child;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => this.#onStdout(chunk));
+        // 서버의 자기 로그다. 프로토콜로 읽지 않고, 실패했을 때 사람에게 보여줄 만큼만 남긴다.
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.#stderr = (this.#stderr + chunk).slice(-STDERR_KEEP);
+        });
+        child.on('error', (error) => this.#fail({ kind: 'SPAWN_FAILED', detail: String(error) }));
+        // 자식이 먼저 죽으면 기다리던 요청이 영원히 매달린다. 전부 깨워서 이유를 준다.
+        child.on('exit', (code, signal) => this.#fail({
+            kind: 'PROCESS_EXITED',
+            detail: `JAM이 먼저 종료했다 (code=${code ?? 'null'}, signal=${signal ?? 'null'})${this.#tail()}`,
+        }));
+        const handshake = await this.#request('initialize', {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {},
+            clientInfo: { name: 'asc', version: '0.1.0' },
+        });
+        if (!handshake.ok)
+            return handshake;
+        const info = handshake.value;
+        // 버전이 다르면 조용히 계속하지 않는다 — 뒤에서 모양이 어긋나면 원인을 못 찾는다.
+        if (info?.protocolVersion !== PROTOCOL_VERSION) {
+            return {
+                ok: false,
+                kind: 'PROTOCOL_ERROR',
+                detail: `protocol 버전이 다르다 — 기대 ${PROTOCOL_VERSION}, 받음 ${String(info?.protocolVersion)}`,
+            };
+        }
+        this.#notify('notifications/initialized');
+        this.#ready = true;
+        return {
+            ok: true,
+            value: { name: info.serverInfo?.name ?? '', version: info.serverInfo?.version ?? '' },
+        };
+    }
+    /** tool 하나를 부르고 text content를 JSON으로 푼다. */
+    async callTool(name, args) {
+        if (!this.#ready) {
+            const started = await this.start();
+            if (!started.ok)
+                return started;
+        }
+        const response = await this.#request('tools/call', { name, arguments: args });
+        if (!response.ok)
+            return response;
+        const payload = response.value;
+        const text = payload?.content?.find((part) => part.type === 'text')?.text;
+        if (typeof text !== 'string') {
+            return { ok: false, kind: 'PROTOCOL_ERROR', detail: `${name}: text content가 없다` };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            return { ok: false, kind: 'PROTOCOL_ERROR', detail: `${name}: 응답이 JSON이 아니다` };
+        }
+        // 서버가 실패를 알린 것과 우리가 못 읽은 것은 다르다. 앞의 것은 서버 말을 그대로 옮긴다.
+        if (payload.isError) {
+            const error = parsed?.error;
+            return {
+                ok: false,
+                kind: 'TOOL_ERROR',
+                detail: error?.code ? `${error.code}: ${error.message ?? ''}` : `${name} 실패`,
+            };
+        }
+        return { ok: true, value: parsed };
+    }
+    /** 자식을 정리한다. 여러 번 불러도 안전하다. */
+    async stop() {
+        const child = this.#child;
+        this.#child = null;
+        this.#ready = false;
+        if (!child || child.exitCode !== null)
+            return;
+        child.stdin.end();
+        child.kill();
+    }
+    // ── 내부 ──────────────────────────────────────────────────────────────────
+    #request(method, params) {
+        const child = this.#child;
+        if (!child)
+            return Promise.resolve({ ok: false, kind: 'SPAWN_FAILED', detail: '프로세스가 없다' });
+        if (this.#exited)
+            return Promise.resolve({ ok: false, ...this.#exited });
+        const id = this.#nextId++;
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                resolve({
+                    ok: false,
+                    kind: 'TIMEOUT',
+                    detail: `${method}: ${this.#deps.timeoutMs ?? 30_000}ms 안에 답하지 않았다${this.#tail()}`,
+                });
+            }, this.#deps.timeoutMs ?? 30_000);
+            this.#pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve({ ok: true, value });
+                },
+                reject: (failure) => {
+                    clearTimeout(timer);
+                    resolve({ ok: false, ...failure });
+                },
+            });
+            try {
+                child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+            }
+            catch (error) {
+                this.#pending.delete(id);
+                clearTimeout(timer);
+                resolve({ ok: false, kind: 'PROCESS_EXITED', detail: String(error) });
+            }
+        });
+    }
+    #notify(method) {
+        try {
+            this.#child?.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', method })}\n`);
+        }
+        catch {
+            // 알림은 답을 기다리지 않는다. 못 보냈으면 다음 요청이 어차피 실패로 말해 준다.
+        }
+    }
+    /** 개행 구분 JSON. 한 줄이 깨져도 그 줄만 버리고 스트림을 통째로 포기하지 않는다. */
+    #onStdout(chunk) {
+        this.#buffer += chunk;
+        for (;;) {
+            const newline = this.#buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = this.#buffer.slice(0, newline).trim();
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (line.length === 0)
+                continue;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                // 서버가 stdout에 프로토콜이 아닌 것을 흘렸다. 기다리는 요청을 매달아 두는 것보다
+                // 이유를 주고 끊는 편이 낫다.
+                this.#fail({ kind: 'PROTOCOL_ERROR', detail: '응답 한 줄이 JSON이 아니다' });
+                continue;
+            }
+            if (typeof message.id !== 'number')
+                continue; // 알림이다 — 기다리는 쪽이 없다
+            const waiting = this.#pending.get(message.id);
+            if (!waiting)
+                continue; // 이미 시간이 지나 포기한 요청
+            this.#pending.delete(message.id);
+            if (message.error) {
+                waiting.reject({
+                    kind: 'PROTOCOL_ERROR',
+                    detail: `JSON-RPC 오류 ${message.error.code ?? ''}: ${message.error.message ?? ''}`,
+                });
+            }
+            else {
+                waiting.resolve(message.result);
+            }
+        }
+    }
+    /** 기다리는 요청 전부를 같은 이유로 깨운다. */
+    #fail(failure) {
+        this.#exited = failure;
+        for (const waiting of this.#pending.values())
+            waiting.reject(failure);
+        this.#pending.clear();
+    }
+    /** 진단 꼬리표. 서버 로그의 마지막 조각만 붙인다 — 자격 값은 애초에 여기 오지 않는다. */
+    #tail() {
+        const tail = this.#stderr.trim().split('\n').at(-1);
+        return tail ? ` — 서버 마지막 출력: ${tail.slice(0, 200)}` : '';
+    }
+}

package/dist/adapters/jam/ports.d.ts

@@ -0,0 +1,51 @@
+import type { InventoryPage, InventoryPort, InventoryQuery } from '../../ports/inventory.ts';
+import type { CommentQuery, ContextComment, ResourceContextPort, ResourceSnapshot } from '../../ports/resource-context.ts';
+import type { JamMcpClient } from './mcp-client.ts';
+/** JAM이 모든 결과에 붙여 주는 완결성 표식. 이 값을 접으면 잘린 목록이 "전체"가 된다. */
+export type JamMeta = {
+    complete?: boolean;
+    commentsComplete?: boolean;
+    overflow?: string[];
+    missingKeys?: string[];
+    reason?: string;
+    notes?: string[];
+};
+export type JamPortsDeps = {
+    client: JamMcpClient;
+    /** Jira project key. `.jira-agent/project.yaml` 이 선언한 값이며 추측하지 않는다. */
+    projectKey: string;
+    /**
+     * JQL 날짜 리터럴을 해석할 timezone(IANA). **Jira 계정의 timezone이며 기계의 것이
+     * 아니다.** 선언하지 않으면 `DEFAULT_TIMEZONE`.
+     */
+    timezone?: string;
+};
+declare class JamBase {
+    readonly id = "jam";
+    protected client: JamMcpClient;
+    protected projectKey: string;
+    protected timezone: string;
+    constructor(deps: JamPortsDeps);
+}
+/**
+ * 상태 무관 열거. 여기서 `scope` 를 고르는 규칙이 이 adapter의 핵심 판단이다.
+ *
+ * 이 Port의 소비자는 회수 경로(Reconcile·Census)이고 그 둘은 **빠짐없음이 성립해야**
+ * 의미가 있다. 그래서 항상 `complete` 로 부른다 — "호출이 작아 보이니 preview" 같은
+ * 추측으로 정하지 않는다. 값싼 훑기(preview)는 쓸 자리가 생기면 그때 연다.
+ */
+export declare class JamInventory extends JamBase implements InventoryPort {
+    enumerate(query: InventoryQuery, cursor?: string): Promise<InventoryPage>;
+}
+export declare class JamResourceContext extends JamBase implements ResourceContextPort {
+    getResource(reference: string): Promise<ResourceSnapshot>;
+    /**
+     * 논의는 full에만 실린다.
+     *
+     * **`commentsComplete === false` 를 "댓글 없음"으로 접지 않는다.** 예산을 넘기면 JAM이
+     * 오래된 것부터 떨어뜨리는데, 그것을 조용히 받으면 조사 단계가 "논의를 다 봤다"고
+     * 착각한다. 그래서 잘렸다는 사실을 항목 하나로 끼워 넣어 사람이 보게 한다.
+     */
+    getComments(reference: string, query?: CommentQuery): Promise<ContextComment[]>;
+}
+export {};

package/dist/adapters/jam/ports.js

@@ -0,0 +1,167 @@
+// JAM 작업 항목 Adapter — Inventory · ResourceContext.
+//
+// ASC는 이 파일 밖에서 Jira를 알지 못한다. REST·자격·문서 포맷·pagination 정책은 전부
+// JAM 뒤에 있고, 여기서는 tool 세 개의 응답을 Port 모양으로 옮기기만 한다.
+//
+// 이 adapter가 **제공하지 않는 것**이 제공하는 것만큼 중요하다:
+//   context.history  JAM이 changelog를 주지 않는다. 없는 것을 있는 척하지 않는다
+//   observe.delta    푸시가 없다. `updated >= …` 조회는 EventSource가 아니라 회수 경로다
+/**
+ * `updated` 는 분 단위 정밀도라 기준선을 그대로 쓰면 같은 분에 몰린 변경을 놓친다.
+ * 조금 뒤로 물려 겹쳐 읽는다 — 누락보다 중복이 안전하고, 중복은 revision 비교가 거른다
+ * (OM §10.5, event-source의 overlap과 같은 이유).
+ */
+const OVERLAP_MS = 60_000;
+/**
+ * JQL이 시각을 읽는 timezone. **JQL 날짜 리터럴에는 offset을 적을 자리가 없다** —
+ * `"2026/08/26 09:04"` 는 Jira 계정의 timezone으로 해석된다. 그래서 이 값은 ASC가 도는
+ * 기계의 timezone이 아니라 **Jira 쪽 timezone**이며, 선언하지 않으면 UTC로 읽는다.
+ *
+ * 기본값을 host timezone으로 두지 않는 이유: 같은 순간이 기계마다 다른 JQL이 되고,
+ * 그 차이는 조회 결과의 차이라 조용히 누락으로 나타난다(3-OS CI에서 실제로 드러났다).
+ *
+ * 잘못 선언했을 때의 방향도 남긴다 — 실제 Jira보다 **동쪽**을 선언하면 기준선이 앞으로
+ * 밀려 그만큼을 놓치고, **서쪽**을 선언하면 겹쳐 읽어 중복이 는다. 모를 때의 UTC는
+ * 한국·일본처럼 동쪽 계정에 대해 안전한 쪽(중복)으로 틀린다.
+ */
+const DEFAULT_TIMEZONE = 'UTC';
+/**
+ * JQL 리터럴로 안전한 시각 문자열. JAM은 JQL을 그대로 통과시키므로 여기서 다듬는다.
+ *
+ * 같은 순간은 어느 기계에서 불러도 같은 문자열이어야 한다 — 그래서 `Date` 의 host 기준
+ * getter(`getHours()` 등)를 쓰지 않고 timezone을 명시해 서식한다.
+ */
+function jqlTime(iso, timeZone) {
+    const at = new Date(new Date(iso).getTime() - OVERLAP_MS);
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hour12: false,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+    }).formatToParts(at);
+    const of = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    // `hour12: false` 로도 자정을 `24` 로 주는 구현이 있다 — 그대로 두면 JQL이 거절한다.
+    const hour = of('hour') === '24' ? '00' : of('hour');
+    return `${of('year')}/${of('month')}/${of('day')} ${hour}:${of('minute')}`;
+}
+class JamBase {
+    id = 'jam';
+    client;
+    projectKey;
+    timezone;
+    constructor(deps) {
+        this.client = deps.client;
+        this.projectKey = deps.projectKey;
+        this.timezone = deps.timezone ?? DEFAULT_TIMEZONE;
+    }
+}
+/**
+ * 상태 무관 열거. 여기서 `scope` 를 고르는 규칙이 이 adapter의 핵심 판단이다.
+ *
+ * 이 Port의 소비자는 회수 경로(Reconcile·Census)이고 그 둘은 **빠짐없음이 성립해야**
+ * 의미가 있다. 그래서 항상 `complete` 로 부른다 — "호출이 작아 보이니 preview" 같은
+ * 추측으로 정하지 않는다. 값싼 훑기(preview)는 쓸 자리가 생기면 그때 연다.
+ */
+export class JamInventory extends JamBase {
+    async enumerate(query, cursor) {
+        // JAM은 cursor를 노출하지 않는다. 페이지 순회는 JAM 안에서 끝나므로 ASC가 이어받을
+        // 지점이 없다 — 두 번째 페이지 요청은 성립하지 않는다.
+        if (cursor)
+            return { items: [], complete: true };
+        const clauses = [`project = ${this.projectKey}`];
+        if (query.updatedSince)
+            clauses.push(`updated >= "${jqlTime(query.updatedSince, this.timezone)}"`);
+        const response = await this.client.callTool('jira_search', {
+            jql: `${clauses.join(' AND ')} ORDER BY updated ASC`,
+            scope: 'complete',
+        });
+        // 못 읽은 것을 "없다"로 돌려주면 census가 멀쩡한 항목을 사라졌다고 본다.
+        if (!response.ok)
+            return { items: [], complete: false };
+        const { issues = [], meta = {} } = response.value;
+        return {
+            items: issues.map((issue) => ({
+                reference: issue.key,
+                state: issue.status,
+                updatedAt: issue.updated,
+                // 이 provider가 주는 유일한 변화 신호다. 필드 단위 delta는 알 수 없다.
+                revisionMarker: issue.updated,
+                title: issue.summary,
+                assignees: issue.assignee ? [issue.assignee] : [],
+                labels: [...(issue.labels ?? []), ...(issue.components ?? [])],
+            })),
+            // JAM이 완결을 부인하면 그대로 옮긴다. Core가 이 값을 보고 상실 판정·기준선 이동을
+            // 모두 보류한다 (C-07 §1.5·§8.2).
+            complete: meta.complete === true,
+        };
+    }
+}
+export class JamResourceContext extends JamBase {
+    async getResource(reference) {
+        const response = await this.client.callTool('jira_context', { issueKeys: [reference] });
+        if (!response.ok)
+            return missing(reference);
+        const issue = response.value.issues?.[0];
+        // 안 돌아온 키는 없는 것일 수도, 안 보이는 것일 수도 있다. provider가 둘을 합쳐 주므로
+        // 우리도 합쳐진 사실 이상을 지어내지 않는다.
+        if (!issue)
+            return missing(reference);
+        const related = [
+            ...(issue.parent?.key ? [issue.parent.key] : []),
+            ...(issue.subtasks ?? []).flatMap((sub) => (sub.key ? [sub.key] : [])),
+            ...(issue.links ?? []).flatMap((link) => (link.issue?.key ? [link.issue.key] : [])),
+        ];
+        return {
+            reference,
+            state: issue.status,
+            title: issue.summary,
+            ...(issue.description ? { body: issue.description } : {}),
+            ...(issue.assignee ? { assignees: [issue.assignee] } : {}),
+            labels: [...(issue.labels ?? []), ...(issue.components ?? [])],
+            updatedAt: issue.updated,
+            revisionMarker: issue.updated,
+            ...(related.length > 0 ? { related } : {}),
+        };
+    }
+    /**
+     * 논의는 full에만 실린다.
+     *
+     * **`commentsComplete === false` 를 "댓글 없음"으로 접지 않는다.** 예산을 넘기면 JAM이
+     * 오래된 것부터 떨어뜨리는데, 그것을 조용히 받으면 조사 단계가 "논의를 다 봤다"고
+     * 착각한다. 그래서 잘렸다는 사실을 항목 하나로 끼워 넣어 사람이 보게 한다.
+     */
+    async getComments(reference, query = {}) {
+        const response = await this.client.callTool('jira_full', { issueKeys: [reference] });
+        if (!response.ok)
+            return [];
+        const issue = response.value.issues?.[0];
+        if (!issue)
+            return [];
+        const comments = (issue.comments ?? []).slice(0, query.limit ?? 20).map((comment) => ({
+            id: comment.id,
+            author: comment.author ?? '(unknown)',
+            at: comment.updated ?? comment.created,
+            body: comment.body,
+        }));
+        if (response.value.meta?.commentsComplete === false) {
+            comments.push({
+                id: 'jam:incomplete',
+                author: '(ASC)',
+                at: new Date(0).toISOString(),
+                body: '이 논의는 일부만 받았다 — provider가 예산 안에서 잘라 보냈다. 전부 보려면 원본을 열어라.',
+            });
+        }
+        return comments;
+    }
+}
+const missing = (reference) => ({
+    reference,
+    state: 'unknown',
+    title: '',
+    updatedAt: '',
+    revisionMarker: '',
+    missing: true,
+});

package/dist/adapters/local/identity.d.ts

@@ -0,0 +1,27 @@
+import type { IdentityBinding } from '../../ports/approval.ts';
+export type IdentityMap = Readonly<Record<string, readonly string[]>>;
+/**
+ * `controller identity → [채널:actor, ...]` 매핑으로 판정한다.
+ *
+ * @example
+ * new LocalIdentityBinding({ 'controller-a': ['local:colosair', 'mattermost:@colosair'] })
+ */
+export declare class LocalIdentityBinding implements IdentityBinding {
+    #private;
+    constructor(map: IdentityMap);
+    verify({ channel, actor, authorizedApprover, }: {
+        channel: string;
+        actor: string;
+        authorizedApprover: string;
+    }): Promise<boolean>;
+}
+/**
+ * **테스트와 명시적 opt-in 전용. 정상 경로에서 쓰지 말 것.**
+ * 켜는 순간 승인자 검증이 사라져 어떤 이름으로 부르든 통과한다.
+ * 실제 운용에서 이걸 고르는 것은 승인 계층을 없애는 결정이며, 그렇게 고른 코드는
+ * 그 사실을 사람에게 보여야 한다.
+ */
+export declare class UnverifiedIdentityBinding implements IdentityBinding {
+    readonly unverified = true;
+    verify(): Promise<boolean>;
+}

package/dist/adapters/local/identity.js

@@ -0,0 +1,40 @@
+// Local Identity Binding — 어떤 actor가 승인 권한자인지 판정한다 (OM §11.6).
+//
+// **이 계층이 하는 일과 하지 않는 일**
+//   한다:    주어진 `채널:actor` 가 그 요청의 승인 권한자로 지정돼 있는지 확인한다.
+//            로컬이라는 이유만으로 통과시키지 않고, 매핑에 없는 이름은 거절한다.
+//   안 한다: 지금 명령을 낸 주체가 사람이라는 증명. 셸을 쓸 수 있는 Agent는 매핑된
+//            이름을 그대로 댈 수 있다. 이 매핑은 신원 확인이지 현장 인증이 아니다.
+//
+// 강한 local authentication(OS 사용자 확인·서명·대화형 확인)은 별도 후속 범위다.
+// 그전까지 결정 표면은 "사람이 조작하는 표면"이라는 계약 위에서 동작한다.
+//
+// Identity는 Credential이 아니다. 여기에는 누가 누구인지만 있고 비밀은 없다 (OM §4.5).
+// Profile/Override에서 매핑을 읽어오는 경로는 B-10에서 붙인다.
+/**
+ * `controller identity → [채널:actor, ...]` 매핑으로 판정한다.
+ *
+ * @example
+ * new LocalIdentityBinding({ 'controller-a': ['local:colosair', 'mattermost:@colosair'] })
+ */
+export class LocalIdentityBinding {
+    #allowed;
+    constructor(map) {
+        this.#allowed = new Map(Object.entries(map).map(([approver, ids]) => [approver, new Set(ids)]));
+    }
+    async verify({ channel, actor, authorizedApprover, }) {
+        return this.#allowed.get(authorizedApprover)?.has(`${channel}:${actor}`) ?? false;
+    }
+}
+/**
+ * **테스트와 명시적 opt-in 전용. 정상 경로에서 쓰지 말 것.**
+ * 켜는 순간 승인자 검증이 사라져 어떤 이름으로 부르든 통과한다.
+ * 실제 운용에서 이걸 고르는 것은 승인 계층을 없애는 결정이며, 그렇게 고른 코드는
+ * 그 사실을 사람에게 보여야 한다.
+ */
+export class UnverifiedIdentityBinding {
+    unverified = true;
+    async verify() {
+        return true;
+    }
+}

package/dist/adapters/local/presentation.d.ts

@@ -0,0 +1,14 @@
+import type { DecisionSummary } from '../../core/view/decision-view.ts';
+import type { DeliveryOutcome, DigestBatch, PresentationCapability, PresentationPort } from '../../ports/presentation.ts';
+export type LocalPresentationDeps = {
+    /** 어디로 내보낼지. 주입받는 이유는 테스트가 화면을 붙잡지 않기 위해서다. */
+    write?: (line: string) => void;
+};
+export declare class LocalPresentation implements PresentationPort {
+    #private;
+    readonly id = "local";
+    readonly capabilities: ReadonlySet<PresentationCapability>;
+    constructor(deps?: LocalPresentationDeps);
+    presentDigest(batch: DigestBatch): Promise<DeliveryOutcome>;
+    presentUrgent(item: DecisionSummary): Promise<DeliveryOutcome>;
+}