@asc-agent/runtime 0.2.0 → 0.3.0

package/dist/adapters/gitlab/adapter.js

@@ -4,7 +4,7 @@
 // Adapter 계약이 실제로 계약이라는 증거다.
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { GitLabClient, discoverToken, encodeProject } from "./client.js";
+import { GitLabClient, discoverToken, encodeProject, glabAvailable } from "./client.js";
 const run = promisify(execFile);
 const PROVIDES = [
     'observe.delta',
@@ -20,6 +20,11 @@ const PROVIDES = [
  * provider 목록을 아는 물건이 됐다는 뜻이다.
  */
 const CLAIMED_ELSEWHERE = new Set(['github.com']);
+/** 기본 실행 통로. 실패는 예외로 올린다 — 호출측이 "없다"와 "터졌다"를 구분한다. */
+const defaultRun = async (command, args) => {
+    const { stdout } = await run(command, [...args]);
+    return stdout;
+};
 export class GitLabAdapter {
     #listRemotes;
     #findToken;
@@ -33,7 +38,9 @@ export class GitLabAdapter {
      * 그렇지 않은 호출자는 `ASC_GITLAB_URL` 로 명시하면 된다.
      */
     #endpoints = new Map();
+    #run;
     constructor(deps = {}) {
+        this.#run = deps.run ?? defaultRun;
         this.#listRemotes = deps.listRemotes ?? defaultListRemotes;
         this.#findToken = deps.findToken ?? discoverToken;
         this.#reach = deps.reach;
@@ -44,7 +51,7 @@ export class GitLabAdapter {
             id: 'gitlab',
             version: '1',
             provides: PROVIDES,
-            requiresCredential: ['ASC_GITLAB_TOKEN | GITLAB_TOKEN'],
+            requiresCredential: ['ASC_GITLAB_TOKEN | GITLAB_TOKEN, 또는 로그인된 glab (읽기 전용)'],
             prerequisites: ['git remote 가 이 host를 가리켜야 한다'],
         };
     }
@@ -80,7 +87,19 @@ export class GitLabAdapter {
     async probe(candidate, context) {
         const token = this.#findToken(context.env);
         if (!token) {
-            return { state: 'UNCONFIGURED', detail: '토큰이 없다 — ASC_GITLAB_TOKEN 또는 GITLAB_TOKEN 을 두어라' };
+            // 토큰이 없다고 통로가 없는 것은 아니다 — 사람이 이미 `glab` 에 로그인해 뒀다면
+            // 그 도구에게 요청을 대신 보내 달라고 할 수 있다. 토큰을 꺼내 오지는 않는다.
+            if (await glabAvailable(this.#run)) {
+                return {
+                    state: 'DEGRADED',
+                    provides: candidate.provides,
+                    detail: '토큰은 없지만 로그인된 glab 를 통로로 쓴다 (읽기 전용)',
+                };
+            }
+            return {
+                state: 'UNCONFIGURED',
+                detail: '토큰이 없다 — ASC_GITLAB_TOKEN 또는 GITLAB_TOKEN 을 두거나, `glab auth login` 을 해 두어라',
+            };
         }
         const baseUrl = context.env?.ASC_GITLAB_URL ?? this.#endpoints.get(candidate.resource);
         const reach = this.#reach ?? ((project, secret) => defaultReach(project, secret, baseUrl));

package/dist/adapters/gitlab/client.d.ts

@@ -15,7 +15,33 @@ export type GitLabResponse<T> = {
 };
 /** 환경변수에서만 찾는다. 값을 파일이나 Profile에 남기지 않는다. */
 export declare function discoverToken(env?: NodeJS.ProcessEnv): string | null;
-export declare class GitLabClient {
+/**
+ * 이미 로그인된 `glab` 을 통로로 쓸 수 있는가 (P1-H).
+ *
+ * 토큰을 꺼내 오지 않는다 — 꺼낼 수 있어도 하지 않는다. 자격은 그 도구 안에 있고, ASC 는
+ * 그 도구에게 **요청을 대신 보내 달라고** 부탁할 뿐이다. env 토큰이 있으면 그쪽이 먼저다:
+ * 명시적으로 준 것이 추론보다 앞선다.
+ */
+export type ProcessRunner = (command: string, args: readonly string[]) => Promise<string>;
+export declare function glabAvailable(run: ProcessRunner): Promise<boolean>;
+/**
+ * `glab api` 를 읽기 통로로 감싼 클라이언트. GET 만 다룬다 — 쓰기는 Grant 를 지나야 하고,
+ * 그 경로를 우회하는 통로를 여기에 만들지 않는다.
+ */
+export declare class GlabApiClient implements GitLabReader {
+    #private;
+    constructor(run: ProcessRunner);
+    get<T>(path: string): Promise<GitLabResponse<T>>;
+}
+/**
+ * 읽기 통로. GitLabClient(토큰)와 GlabApiClient(로그인된 도구) 둘 다 이것이다 —
+ * Port 들은 어느 쪽인지 몰라야 한다. 통로가 바뀌었다고 조회 코드가 바뀌면, 통로를 늘릴
+ * 때마다 같은 코드가 갈라진다.
+ */
+export interface GitLabReader {
+    get<T>(path: string): Promise<GitLabResponse<T>>;
+}
+export declare class GitLabClient implements GitLabReader {
     #private;
     constructor(deps: GitLabClientDeps);
     get<T>(path: string): Promise<GitLabResponse<T>>;

package/dist/adapters/gitlab/client.js

@@ -10,6 +10,36 @@
 export function discoverToken(env = process.env) {
     return env.ASC_GITLAB_TOKEN ?? env.GITLAB_TOKEN ?? null;
 }
+export async function glabAvailable(run) {
+    try {
+        await run('glab', ['auth', 'status']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `glab api` 를 읽기 통로로 감싼 클라이언트. GET 만 다룬다 — 쓰기는 Grant 를 지나야 하고,
+ * 그 경로를 우회하는 통로를 여기에 만들지 않는다.
+ */
+export class GlabApiClient {
+    #run;
+    constructor(run) {
+        this.#run = run;
+    }
+    async get(path) {
+        try {
+            // 페이지 헤더는 `glab api` 가 돌려주지 않는다. 다음 페이지를 모르는 채로
+            // 있다고 말하지 않는다 — nextPage 를 비워 두면 호출측이 한 페이지로 끝낸다.
+            const stdout = await this.#run('glab', ['api', path.replace(/^\//, '')]);
+            return { ok: true, status: 200, data: JSON.parse(stdout) };
+        }
+        catch (error) {
+            return { ok: false, status: 0, data: null, error: String(error.message ?? error).slice(0, 200) };
+        }
+    }
+}
 export class GitLabClient {
     #token;
     #fetch;

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

@@ -2,16 +2,16 @@ import type { ChangeContextPort, ChangeSummary } from '../../ports/change-contex
 import type { Cursor, EventBatch, EventSource } from '../../ports/event-source.ts';
 import type { InventoryPage, InventoryPort, InventoryQuery } from '../../ports/inventory.ts';
 import type { CommentQuery, ContextComment, ResourceContextPort, ResourceSnapshot } from '../../ports/resource-context.ts';
-import { type GitLabClient } from './client.ts';
+import { type GitLabReader } from './client.ts';
 export type GitLabDeps = {
-    client: GitLabClient;
+    client: GitLabReader;
     /** `group/sub/project`. */
     project: string;
     perPage?: number;
 };
 declare abstract class GitLabBase {
     readonly id: string;
-    protected client: GitLabClient;
+    protected client: GitLabReader;
     protected project: string;
     protected perPage: number;
     constructor(deps: GitLabDeps);

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

@@ -11,6 +11,10 @@ export type JamAdapterDeps = {
     authStatus?: (context: DiscoveryContext) => Promise<AuthStatus>;
     /** 선언 파일 읽기 통로. */
     readDeclaration?: (projectRoot: string) => Promise<string | null>;
+    /** 개인 선언 파일 읽기 통로. */
+    readPersonalBindings?: (home: string) => Promise<string | null>;
+    /** 이 저장소의 remote 들. 개인 선언과 맞출 때만 쓴다. */
+    listRemotes?: (projectRoot: string) => Promise<string[]>;
 };
 /** `jam auth status --json` 의 응답. **토큰 값은 여기 오지 않는다.** */
 export type AuthStatus = {
@@ -51,3 +55,13 @@ export declare class JamAdapter implements Adapter {
     /** 프로젝트와 무관하게 "도구가 지금 쓸 수 있는가". binding 유무와 별개 사실이다. */
     runtime(context: DiscoveryContext): Promise<RuntimeStatus>;
 }
+/**
+ * 개인 선언에서 `workspace` 와 `key` 짝만 꺼낸다. YAML 파서를 들이지 않는다 —
+ * 읽을 것이 두 줄이고, 의존성 하나가 그 값보다 비싸다.
+ */
+export declare function parsePersonalBindings(text: string): {
+    workspace: string;
+    key: string;
+}[];
+/** `git:host/group/project` 형태로 맞춘다. remote URL 도 같은 형태로 접어 비교한다. */
+export declare function normalizeWorkspace(value: string): string | null;

package/dist/adapters/jam/adapter.js

@@ -5,6 +5,7 @@
 // 로그인을 대신 실행하면 그 설계를 우회하는 것이다 — 하지 않는다.
 import { execFile } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 const run = promisify(execFile);
@@ -26,8 +27,16 @@ const PROVIDES = [
     'context.resource',
     'context.thread',
 ];
-/** 프로젝트가 어느 작업 항목 묶음에 붙어 있는지 선언하는 파일. 없으면 붙어 있지 않은 것이다. */
+/** 프로젝트가 어느 작업 항목 묶음에 붙어 있는지 선언하는 파일. 팀이 채택했을 때 저장소에 생긴다. */
 const DECLARATION = join('.jira-agent', 'project.yaml');
+/**
+ * 같은 선언의 **개인 자리**. 저장소를 건드리지 않고 붙여 쓰는 것이 provider 의 기본값이라,
+ * 저장소 안만 보면 "붙어 있는데 안 붙은 것으로 보이는" 경우가 생긴다. 그 상태에서 조사를
+ * 포기하면 읽을 수 있는 것을 안 읽은 것이 된다 — 그래서 여기도 본다.
+ *
+ * 개인 선언은 remote 로 맞춘다(파일의 `path` 는 출처 기록일 뿐이다).
+ */
+const PERSONAL_BINDINGS = join('.jam', 'projects.yaml');
 /**
  * 어떻게 실행할 것인가.
  *
@@ -54,11 +63,15 @@ export class JamAdapter {
     #args;
     #authStatus;
     #readDeclaration;
+    #readPersonalBindings;
+    #listRemotes;
     constructor(deps = {}) {
         this.#command = deps.command ?? 'jam';
         this.#args = deps.args ?? [];
         this.#authStatus = deps.authStatus;
         this.#readDeclaration = deps.readDeclaration ?? defaultRead;
+        this.#readPersonalBindings = deps.readPersonalBindings ?? defaultReadPersonal;
+        this.#listRemotes = deps.listRemotes ?? defaultListRemotes;
     }
     describe() {
         return {
@@ -81,12 +94,30 @@ export class JamAdapter {
      */
     async discover(context) {
         const text = await this.#readDeclaration(context.projectRoot);
-        if (!text)
-            return [];
-        const key = parseProjectKey(text);
-        if (!key)
+        const key = text ? parseProjectKey(text) : null;
+        if (key)
+            return [{ adapterId: 'jam', resource: key, provides: PROVIDES, discoveredBy: DECLARATION }];
+        // 저장소에 선언이 없다고 붙어 있지 않은 것은 아니다 — 개인 자리를 본다.
+        const personal = await this.#personalKey(context);
+        if (!personal)
             return [];
-        return [{ adapterId: 'jam', resource: key, provides: PROVIDES, discoveredBy: DECLARATION }];
+        return [{ adapterId: 'jam', resource: personal, provides: PROVIDES, discoveredBy: PERSONAL_BINDINGS }];
+    }
+    /** 개인 선언에서 이 저장소의 키를 찾는다. remote 가 일치할 때만 — 이름이 비슷한 것은 근거가 아니다. */
+    async #personalKey(context) {
+        const home = context.env?.ASC_JAM_HOME ?? context.env?.HOME ?? homedir();
+        const text = await this.#readPersonalBindings(home);
+        if (!text)
+            return null;
+        const remotes = await this.#listRemotes(context.projectRoot).catch(() => []);
+        const mine = new Set(remotes.map(normalizeWorkspace).filter((value) => value !== null));
+        if (mine.size === 0)
+            return null;
+        for (const entry of parsePersonalBindings(text)) {
+            if (mine.has(entry.workspace))
+                return entry.key;
+        }
+        return null;
     }
     async probe(candidate, context) {
         const status = await this.#status(context);
@@ -142,3 +173,50 @@ async function defaultRead(projectRoot) {
         return null;
     }
 }
+async function defaultReadPersonal(home) {
+    try {
+        return await readFile(join(home, PERSONAL_BINDINGS), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+async function defaultListRemotes(projectRoot) {
+    const { stdout } = await run('git', ['-C', projectRoot, 'remote', '-v']);
+    return stdout
+        .split('\n')
+        .map((line) => line.split(/\s+/)[1])
+        .filter((url) => Boolean(url));
+}
+/**
+ * 개인 선언에서 `workspace` 와 `key` 짝만 꺼낸다. YAML 파서를 들이지 않는다 —
+ * 읽을 것이 두 줄이고, 의존성 하나가 그 값보다 비싸다.
+ */
+export function parsePersonalBindings(text) {
+    const found = [];
+    let workspace = null;
+    for (const line of text.split('\n')) {
+        const w = /^\s*-?\s*workspace:\s*"?([^"\n]+?)"?\s*$/.exec(line);
+        if (w?.[1]) {
+            workspace = w[1];
+            continue;
+        }
+        const k = /^\s*key:\s*"?([^"\n]+?)"?\s*$/.exec(line);
+        if (k?.[1] && workspace) {
+            found.push({ workspace: normalizeWorkspace(workspace) ?? workspace, key: k[1] });
+            workspace = null;
+        }
+    }
+    return found;
+}
+/** `git:host/group/project` 형태로 맞춘다. remote URL 도 같은 형태로 접어 비교한다. */
+export function normalizeWorkspace(value) {
+    const raw = value.trim().replace(/^git:/, '');
+    const ssh = /^[^@]+@([^:]+):(.+?)(?:\.git)?$/.exec(raw);
+    const https = /^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/.exec(raw);
+    const plain = /^([^/]+)\/(.+?)(?:\.git)?$/.exec(raw);
+    const match = ssh ?? https ?? plain;
+    if (!match)
+        return null;
+    return `git:${match[1].toLowerCase()}/${match[2].toLowerCase()}`;
+}

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

@@ -38,6 +38,14 @@ export declare class JamInventory extends JamBase implements InventoryPort {
     enumerate(query: InventoryQuery, cursor?: string): Promise<InventoryPage>;
 }
 export declare class JamResourceContext extends JamBase implements ResourceContextPort {
+    /**
+     * `jira_context` 가 아니라 `jira_full` 을 부른다.
+     *
+     * context 단계는 본문(description)을 싣지 않는다. 그런데 ResourceSnapshot 의 `body` 는
+     * 조사와 계약 초안이 완료 조건을 읽는 유일한 자리다 — 그것을 비운 채 넘기면 "작업 항목에
+     * 완료 조건이 없다"는 **거짓 사실**이 만들어지고, 없는 조건을 사람에게 되묻게 된다.
+     * provider 자신의 지침도 계약·합의 판정에는 full 을 쓰라고 말한다.
+     */
     getResource(reference: string): Promise<ResourceSnapshot>;
     /**
      * 논의는 full에만 실린다.
@@ -48,4 +56,5 @@ export declare class JamResourceContext extends JamBase implements ResourceConte
      */
     getComments(reference: string, query?: CommentQuery): Promise<ContextComment[]>;
 }
+export declare function statusIndicatesDone(status: string | undefined): boolean | undefined;
 export {};

package/dist/adapters/jam/ports.js

@@ -100,8 +100,16 @@ export class JamInventory extends JamBase {
     }
 }
 export class JamResourceContext extends JamBase {
+    /**
+     * `jira_context` 가 아니라 `jira_full` 을 부른다.
+     *
+     * context 단계는 본문(description)을 싣지 않는다. 그런데 ResourceSnapshot 의 `body` 는
+     * 조사와 계약 초안이 완료 조건을 읽는 유일한 자리다 — 그것을 비운 채 넘기면 "작업 항목에
+     * 완료 조건이 없다"는 **거짓 사실**이 만들어지고, 없는 조건을 사람에게 되묻게 된다.
+     * provider 자신의 지침도 계약·합의 판정에는 full 을 쓰라고 말한다.
+     */
     async getResource(reference) {
-        const response = await this.client.callTool('jira_context', { issueKeys: [reference] });
+        const response = await this.client.callTool('jira_full', { issueKeys: [reference] });
         if (!response.ok)
             return missing(reference);
         const issue = response.value.issues?.[0];
@@ -109,10 +117,17 @@ export class JamResourceContext extends JamBase {
         // 우리도 합쳐진 사실 이상을 지어내지 않는다.
         if (!issue)
             return missing(reference);
+        // 막는 것을 먼저 싣는다. Core 는 이 배열의 **순서만** 알고 종류는 모른다 — 순서가
+        // 곧 "무엇부터 확인해야 하는가" 다. 상한에 걸려 잘릴 때 blocker 가 부모·하위 작업
+        // 뒤에 밀려 사라지는 것을 막는다.
+        const blocking = (issue.links ?? []).filter((link) => link.blocksThisIssue === true);
+        const otherLinks = (issue.links ?? []).filter((link) => link.blocksThisIssue !== true);
+        const blockedBy = blocking.flatMap((link) => (link.issue?.key ? [link.issue.key] : []));
         const related = [
+            ...blockedBy,
+            ...otherLinks.flatMap((link) => (link.issue?.key ? [link.issue.key] : [])),
             ...(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,
@@ -124,6 +139,7 @@ export class JamResourceContext extends JamBase {
             updatedAt: issue.updated,
             revisionMarker: issue.updated,
             ...(related.length > 0 ? { related } : {}),
+            ...(blockedBy.length > 0 ? { blockedBy } : {}),
         };
     }
     /**
@@ -165,3 +181,34 @@ const missing = (reference) => ({
     revisionMarker: '',
     missing: true,
 });
+/**
+ * tracker 가 "끝났다"고 말하는가. **판정이 아니라 어휘 번역이다** — Core 는 Jira 상태
+ * 문자열을 알면 안 되고(C-09 §6.1), 그렇다고 상태 문자열을 아무도 안 읽으면 "진행 중인데
+ * 이미 병합됨"을 알아볼 수 없다. 그 번역을 adapter 자리에서 한 줄로 한다.
+ *
+ * 모르는 어휘는 undefined 로 남긴다 — 모르는 것을 "안 끝났다"로 읽으면 없는 stale 을 만든다.
+ *
+ * ponytail: 닫힘 상태 목록은 휴리스틱이다. JAM 이 statusCategory 를 실어 주면 그것으로 바꾼다.
+ */
+const DONE_STATUSES = new Set(['done', 'closed', 'resolved', 'complete', 'completed', '완료', '닫힘', '해결됨']);
+const OPEN_STATUSES = new Set([
+    'to do',
+    'todo',
+    'open',
+    'in progress',
+    'in review',
+    'backlog',
+    '해야 할 일',
+    '진행 중',
+    '검토 중',
+]);
+export function statusIndicatesDone(status) {
+    if (!status)
+        return undefined;
+    const normalized = status.trim().toLowerCase();
+    if (DONE_STATUSES.has(normalized))
+        return true;
+    if (OPEN_STATUSES.has(normalized))
+        return false;
+    return undefined;
+}

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

@@ -0,0 +1,15 @@
+import type { LocalRepoPort, RepoObservation, RepoQuery } from '../../ports/local-repo.ts';
+/** 명령 실행. 성공하면 stdout, 실패하면 null — 종료코드로 답하는 질문이 있어서다. */
+export type GitRunner = (args: readonly string[]) => Promise<string | null>;
+export type LocalRepoDeps = {
+    cwd: string;
+    git?: GitRunner;
+    /** 경로 존재 확인. 테스트에서 갈아끼운다. */
+    exists?: (path: string) => Promise<boolean>;
+};
+export declare class LocalRepoAdapter implements LocalRepoPort {
+    #private;
+    readonly id = "local-repo";
+    constructor(deps: LocalRepoDeps);
+    observe(query: RepoQuery): Promise<RepoObservation>;
+}

package/dist/adapters/local/repo.js

@@ -0,0 +1,179 @@
+// 로컬 git 관측. 읽기 전용 서브커맨드만 쓰고, 아무것도 바꾸지 않는다.
+//
+// 실패는 관측 안에서 흡수한다 — git 이 없거나 저장소가 아니면 `unavailable` 이 채워진
+// 빈 관측이 나온다. 던지지 않는 이유는 호출측이 "보려 했으나 못 봤다"와 "아예 안 봤다"를
+// 구분해야 하기 때문이다. 후자는 이 함수를 부르지 않은 것이고, 그건 판정에서 거부된다.
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+const defaultGit = (cwd) => async (args) => {
+    try {
+        const { stdout } = await run('git', ['-C', cwd, ...args]);
+        return stdout;
+    }
+    catch {
+        return null;
+    }
+};
+const defaultExists = async (path) => {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export class LocalRepoAdapter {
+    id = 'local-repo';
+    #cwd;
+    #git;
+    #exists;
+    constructor(deps) {
+        this.#cwd = deps.cwd;
+        this.#git = deps.git ?? defaultGit(deps.cwd);
+        this.#exists = deps.exists ?? defaultExists;
+    }
+    async observe(query) {
+        const head = await this.#git(['rev-parse', '--abbrev-ref', 'HEAD']);
+        if (head === null) {
+            return {
+                branch: null,
+                remotes: [],
+                refs: [],
+                pathsExist: {},
+                unavailable: 'git 저장소를 읽지 못했다 (git 부재 또는 저장소 아님)',
+            };
+        }
+        const observation = {
+            branch: head.trim() || null,
+            remotes: parseRemotes(await this.#git(['remote', '-v'])),
+            refs: [],
+            pathsExist: {},
+        };
+        if (query.refHint) {
+            observation.refs = filterRefs(await this.#git(['for-each-ref', '--format=%(refname:short)', 'refs/heads', 'refs/remotes']), query.refHint);
+        }
+        const canonicalRef = query.canonicalRef ?? (await this.#defaultCanonicalRef());
+        if (canonicalRef) {
+            observation.canonicalRef = canonicalRef;
+            observation.mergedIntoCanonical = await this.#anyMerged(observation.refs, canonicalRef);
+            if (query.refHint) {
+                // 가지가 지워졌어도 이력은 남는다 — 커밋 메시지가 이 작업을 언급하는지 본다.
+                const log = await this.#git(['log', '--format=%h %s', `--grep=${query.refHint}`, '-n', '5', canonicalRef]);
+                const mentions = (log ?? '')
+                    .split('\n')
+                    .map((line) => line.trim())
+                    .filter((line) => line.length > 0);
+                observation.mentionedOnCanonical = mentions;
+                if (mentions.length > 0) {
+                    // 언급만으로는 부족하다. 무엇을 건드린 커밋인지, 그 결과가 지금도 남아 있는지
+                    // 본다 — 되돌린 커밋도 이 작업을 "언급"하기 때문이다.
+                    const survival = await this.#survivalOf(mentions, canonicalRef);
+                    observation.mentionedOnlyReverts = survival.onlyReverts;
+                    if (survival.artifactsPresent !== undefined) {
+                        observation.mentionedArtifactsPresent = survival.artifactsPresent;
+                    }
+                }
+            }
+        }
+        for (const path of query.paths ?? []) {
+            observation.pathsExist[path] = await this.#exists(join(this.#cwd, path));
+        }
+        if ((query.modulePaths?.length ?? 0) > 0) {
+            const modules = {};
+            for (const path of query.modulePaths ?? [])
+                modules[path] = await this.#exists(join(this.#cwd, path));
+            observation.modulesPresent = modules;
+        }
+        if (canonicalRef && (query.paths?.length ?? 0) > 0) {
+            const onCanonical = {};
+            for (const path of query.paths ?? []) {
+                // squash 병합이면 ref 는 조상이 아니다. 산출물이 정본에 있는지는 따로 물어야 한다.
+                onCanonical[path] = (await this.#git(['cat-file', '-e', `${canonicalRef}:${path}`])) !== null;
+            }
+            observation.pathsOnCanonical = onCanonical;
+        }
+        return observation;
+    }
+    /**
+     * Profile 이 정본 ref 를 선언하지 않았을 때, 저장소 자신에게 묻는다 (origin/HEAD).
+     * 추측이 아니라 관측이다 — 없으면 없는 대로 둔다.
+     */
+    async #defaultCanonicalRef() {
+        const head = await this.#git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD']);
+        return head?.trim() || undefined;
+    }
+    /**
+     * 언급 커밋들이 남긴 것이 지금도 있는가. 되돌리기만 있으면 그 사실을 따로 말한다.
+     *
+     * 파일 목록을 하나도 못 읽으면 `artifactsPresent` 는 undefined 다 — "없다"가 아니라
+     * "확인하지 못했다" 이고, 그 둘을 합치면 판정이 거짓을 만든다.
+     */
+    async #survivalOf(mentions, canonicalRef) {
+        const commits = mentions.map((line) => {
+            const at = line.indexOf(' ');
+            return { hash: at > 0 ? line.slice(0, at) : line, subject: at > 0 ? line.slice(at + 1) : '' };
+        });
+        const onlyReverts = commits.every((commit) => /^revert\b/i.test(commit.subject.trim()));
+        let readAny = false;
+        for (const commit of commits) {
+            if (/^revert\b/i.test(commit.subject.trim()))
+                continue;
+            const listed = await this.#git(['show', '--name-status', '--format=', commit.hash]);
+            if (listed === null)
+                continue;
+            readAny = true;
+            for (const path of changedPaths(listed).slice(0, 20)) {
+                if ((await this.#git(['cat-file', '-e', `${canonicalRef}:${path}`])) !== null) {
+                    return { onlyReverts, artifactsPresent: true };
+                }
+            }
+        }
+        return readAny ? { onlyReverts, artifactsPresent: false } : { onlyReverts };
+    }
+    async #anyMerged(refs, canonicalRef) {
+        for (const ref of refs) {
+            if ((await this.#git(['merge-base', '--is-ancestor', ref, canonicalRef])) !== null)
+                return true;
+        }
+        return false;
+    }
+}
+function parseRemotes(stdout) {
+    if (!stdout)
+        return [];
+    const seen = new Map();
+    for (const line of stdout.split('\n')) {
+        const [name, url] = line.trim().split(/\s+/);
+        if (name && url && !seen.has(name))
+            seen.set(name, url);
+    }
+    return [...seen].map(([name, url]) => ({ name, url }));
+}
+function filterRefs(stdout, hint) {
+    if (!stdout)
+        return [];
+    const needle = hint.toLowerCase();
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((ref) => ref.length > 0 && ref.toLowerCase().includes(needle));
+}
+/** `--name-status` 출력에서 지금도 존재할 수 있는 경로만. 삭제(D)는 세지 않는다. */
+function changedPaths(stdout) {
+    const paths = [];
+    for (const line of stdout.split('\n')) {
+        const parts = line.trim().split(/\s+/);
+        const status = parts[0];
+        if (!status || status.startsWith('D'))
+            continue;
+        // 이름이 바뀐 경우(R100 old new)는 새 이름이 지금의 경로다.
+        const path = parts[parts.length - 1];
+        if (path && path !== status)
+            paths.push(path);
+    }
+    return paths;
+}

package/dist/adapters/markdown/state-store.js

@@ -138,6 +138,13 @@ export class MarkdownStateStore {
     async create(kind, entity) {
         const id = String(entity[ENTITY_KEY[kind]]);
         const file = entityFile(this.#root, kind, id);
+        // 회수돼 보관된 id 도 이미 쓴 id 다. 이것을 막지 않으면 같은 이름의 두 계약이 생기고,
+        // 보관 파일이 덮이면서 앞의 기록이 사라진다 (실제로 그렇게 잃었다).
+        const archived = join(archiveDir(this.#root, kind), `${toFileName(id)}.md`);
+        if (await exists(archived)) {
+            const current = (await this.#read(kind, archived));
+            return { ok: false, reason: 'ALREADY_EXISTS', current };
+        }
         try {
             // 'wx'가 원자적 배타 생성이라 락 없이도 중복이 걸린다
             await writeFile(file, serializeEntity(kind, entity), { encoding: 'utf8', flag: 'wx' });
@@ -177,7 +184,12 @@ export class MarkdownStateStore {
             return false;
         const dir = archiveDir(this.#root, kind);
         await mkdir(dir, { recursive: true });
-        await rename(from, join(dir, `${toFileName(id)}.md`));
+        const to = join(dir, `${toFileName(id)}.md`);
+        // 보관은 덮어쓰기가 아니다. 같은 이름이 이미 있으면 옮기지 않고 그대로 둔다 —
+        // 기록 하나를 살리자고 다른 기록을 지우지 않는다.
+        if (await exists(to))
+            return false;
+        await rename(from, to);
         return true;
     }
     // ── Control State ─────────────────────────────────────────────────────────

package/dist/adapters/memory/state-store.js

@@ -36,6 +36,10 @@ export class MemoryStateStore {
         const existing = table.get(id);
         if (existing)
             return { ok: false, reason: 'ALREADY_EXISTS', current: clone(existing) };
+        // 회수된 것도 쓴 id 다. 다시 쓰면 그 기록 위에 다른 계약이 앉는다.
+        const archived = this.#archived.get(kind)?.get(id);
+        if (archived)
+            return { ok: false, reason: 'ALREADY_EXISTS', current: clone(archived) };
         table.set(id, clone(entity));
         return { ok: true, entity: clone(entity) };
     }

package/dist/cli/asc.d.ts

@@ -6,4 +6,10 @@
  * 설치하는 것은 말이 안 되고, 그것을 계획에 넣으면 매 setup이 npm을 부른다.
  */
 export type AscEntry = 'runtime' | 'bootstrap';
+/**
+ * bootstrap이 자기 USAGE에 적을 값. **거기서 손으로 적지 않게 하려고 내보낸다** —
+ * 두 패키지가 각자 버전 문자열을 들면 릴리스마다 한쪽이 뒤처지고, 그 지연은 곧
+ * 사용자가 실행하는 명령이 된다 (0.2.0 회차의 skill.ts가 그랬다).
+ */
+export { BOOTSTRAP_SPEC } from '../core/distribution/release.ts';
 export declare function runAscCommand(argv: string[], entry?: AscEntry): Promise<number>;