@asc-agent/runtime 0.7.1 → 0.8.0

package/dist/adapters/claude-code/install.js

@@ -111,6 +111,42 @@ function reconcileHooks(settings, specs) {
     }
     return { settings: changed.length > 0 ? { ...settings, hooks } : settings, changed };
 }
+/**
+ * ASC control-plane 을 Host 권한 계층에서 통과시키는 규칙 (E-02, 2층).
+ *
+ * 0.7.1 실측에서 raw 외부 write 는 ASC Guard 가 막고, 그 자리의 안전한 출구인
+ * `asc grant issue` 는 Host 의 권한 판정이 막았다. 막는 길과 나가는 길이 동시에 닫히면
+ * 사람이 갇힌다. Host 안에서 우리가 손댈 수 있는 자리는 이 한 줄뿐이다 — 우리 명령을
+ * 명시적으로 허용 목록에 올린다. **허용하는 것은 ASC CLI 뿐이고**, 실행 권한이 있는지는
+ * 그 다음에 Core 가 판정한다 (Guard allows, then Core decides).
+ */
+export const CONTROL_PLANE_ALLOW_RULES = ['Bash(asc:*)'];
+/**
+ * settings 의 permissions.allow 에 우리 규칙을 **더하기만** 한다. 남의 항목은 읽지도
+ * 고치지도 않는다. 이미 있으면 그대로 둔다 — 중복은 그 자체로 결함이다.
+ */
+function reconcileAllow(settings) {
+    const permissions = { ...(settings.permissions ?? {}) };
+    const allow = [...(permissions.allow ?? [])];
+    const added = CONTROL_PLANE_ALLOW_RULES.filter((rule) => !allow.includes(rule));
+    if (added.length === 0)
+        return { settings, added };
+    permissions.allow = [...allow, ...added];
+    return { settings: { ...settings, permissions }, added };
+}
+export async function controlPlaneAccess(paths) {
+    const settings = (await readJson(locate(paths).settings)) ?? {};
+    const permissions = (settings.permissions ?? {});
+    const denied = (permissions.deny ?? []).filter((rule) => /^Bash\(\s*asc[\s:)]/.test(rule));
+    const allowed = CONTROL_PLANE_ALLOW_RULES.every((rule) => (permissions.allow ?? []).includes(rule));
+    if (denied.length > 0)
+        return { allowed: false, denied: true, detail: `the host denies ${denied.join(', ')}` };
+    return {
+        allowed,
+        denied: false,
+        ...(allowed ? {} : { detail: 'the host has no allow rule for ASC commands — `asc refresh` adds it' }),
+    };
+}
 async function readJson(path) {
     try {
         return JSON.parse(await readFile(path, 'utf8'));
@@ -169,6 +205,15 @@ export async function install(paths, now = () => new Date().toISOString(), opts
         written.push(`${where.settings} (${reconciled.changed.join(', ')} hook)`);
     }
     manifest.settingsHook = true;
+    // control-plane 허용 규칙 (E-02). hook 등록과 같은 파일이지만 다른 계약이다 —
+    // hook 은 우리가 막는 자리이고, 이것은 우리가 **막히지 않는** 자리다.
+    const allowed = reconcileAllow((await readJson(where.settings)) ?? {});
+    if (allowed.added.length > 0) {
+        await mkdir(dirname(where.settings), { recursive: true });
+        await writeFile(where.settings, JSON.stringify(allowed.settings, null, 2) + '\n', 'utf8');
+        written.push(`${where.settings} (control-plane allow: ${allowed.added.join(', ')})`);
+    }
+    manifest.permissionAllow = [...new Set([...(manifest.permissionAllow ?? []), ...CONTROL_PLANE_ALLOW_RULES])];
     await mkdir(dirname(where.manifest), { recursive: true });
     await writeFile(where.manifest, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
     return { written, skipped, hookRegistered: true };
@@ -297,6 +342,27 @@ export async function uninstall(paths) {
             removed.push(`${where.settings} (${dropped.join(', ')} hook entry)`);
         }
     }
+    // 우리가 넣은 허용 규칙만 걷는다 — manifest 에 적힌 것만 대상이므로, 사람이 직접
+    // 넣어 둔 같은 규칙을 지우는 일은 생기지 않는다.
+    const mine = manifest.permissionAllow ?? [];
+    if (mine.length > 0) {
+        const current = (await readJson(where.settings)) ?? {};
+        const permissions = (current.permissions ?? {});
+        const before = permissions.allow ?? [];
+        const allow = before.filter((rule) => !mine.includes(rule));
+        if (allow.length !== before.length) {
+            if (allow.length > 0)
+                permissions.allow = allow;
+            else
+                delete permissions.allow;
+            if (Object.keys(permissions).length === 0)
+                delete current.permissions;
+            else
+                current.permissions = permissions;
+            await writeFile(where.settings, JSON.stringify(current, null, 2) + '\n', 'utf8');
+            removed.push(`${where.settings} (control-plane allow)`);
+        }
+    }
     await rm(where.manifest, { force: true });
     await rm(dirname(where.manifest), { recursive: true, force: true }).catch(() => { });
     // 파일만 지우면 빈 skills/<name>/ 이 남는다 (P1 관찰 ⑥). 우리가 만든 디렉터리이므로

package/dist/adapters/claude-code/skill.js

@@ -30,8 +30,9 @@ export function skillText() {
 name: asc
 description: >-
   Safely start, resume or continue a Logical Session in a project that has ASC attached.
-  Triggers — "proceed with ASC", "continue the ASC session", "asc proceed", "start work
-  with ASC", "ASC로 진행해", "ASC 세션 이어서", "ASC로 작업 시작", or the explicit /asc.
+  Triggers — "start this work", "continue the ASC session", "publish it", "wrap it up",
+  "proceed with ASC", "ASC로 진행해", "ASC 세션 이어서", "이거 작업해", "게시해",
+  "마무리해", or the explicit /asc.
   Also triggers on work-status questions in an ASC-attached project — "is this
   implemented?", "what's left to do?", "what should I do now?", "현황 파악",
   "이거 구현됐나", "남은 작업", "지금 뭐 해야 하나" — because answering those by
@@ -48,7 +49,7 @@ CLI — here you call it, act on the typed outcome, and keep the contract.
 
 "Is X implemented?", "what's the status of this work?", "what remains?" — in an
 ASC-attached project, do NOT settle these by direct host exploration (git log, tracker
-reads). Run \`asc proceed --work <KEY>\` first and read its WORK_STATE: it fetches the
+reads). Run \`asc work start <KEY> --json\` first and read its WORK_STATE: it fetches the
 canonical remote, grades the evidence, and refuses to conclude on a stale or key-only
 observation — none of which ad-hoc exploration does. Direct exploration may supplement
 the answer, never replace the judgement. This is mitigation at the model layer; the
@@ -70,20 +71,85 @@ The user does not need to know this sequence. This is the one the skill follows.
      command and ask them to switch this session's permission mode so they can approve the
      single run — a standing allow rule for the command was measured and did not work.
 
-1. Attached?              asc setup status
-     not yet  → asc init (it shows profile candidates; a person chooses)
-     blocked  → show the printed reason and remedy to the person, and stop. Do not open it for them
-2. Anything to run?       asc proceed --json   (act per the table below)
+1. Where are we?          asc status
+     not attached → asc setup (it shows profile candidates; a person chooses)
+     blocked      → show the printed reason and remedy to the person, and stop. Do not open it for them
+2. Anything to run?       asc work start [<WORK-KEY>] --json   (act per the table below)
 3. Check before handing   asc preflight        (paths and decision rights, both)
 4. While working          asc progress report
 5. Another part's call    asc query open / answer
-6. Wrap up                asc session done → tell the person to run asc controller collect
+6. Send it out            asc work publish
+7. Wrap up                asc work finish
 \`\`\`
 
 **Do not open what is blocked.** LOCK_DRIFT, incomplete configuration and an unreadable
-canonical source are all a person's call, and \`setup status\` already states the reason
+canonical source are all a person's call, and \`asc status\` already states the reason
 and the remedy.
 
+## Three axes, and they do not stand in for each other
+
+\`\`\`text
+Agent Management   who owns this work, what its scope is, how far it has come
+Decision Authority whether a person has to decide this
+Execution Mode     who runs the approved act — MANUAL (a person) or AUTO (ASC)
+\`\`\`
+
+**AUTO is not the opposite of human-in-the-loop.** It does not approve anything on a
+person's behalf, and MANUAL does not mean something was already approved. Changing the
+mode never changes a session's owner, scope, progress or handoff.
+
+\`\`\`text
+"수동으로 해" · "let me run it"     → asc mode manual
+"ASC가 자동으로 관리해"             → asc mode auto
+\`\`\`
+
+Stepping down out of AUTO is one command and it is recorded — who said so, and when.
+**Do not use it to get past a block.** If the guard stopped a write, the answer is
+\`asc work publish\`, not a mode change; flipping to MANUAL to push raw is the exact drift
+ASC exists to make visible, and the record makes it visible to the person you work with.
+
+**A workspace nobody has chosen a mode for is not in AUTO.** AUTO exists only where a
+person turned it on and the checks below passed, so a fresh or upgraded
+workspace enforces nothing until someone says so. \`asc status\` says which of the two it is.
+
+\`asc mode auto\` refuses unless three things hold here: a managed write path assembles, the
+guard is installed, and ASC's own commands still run in this host. Whether a *particular*
+action can go out is answered when that action is attempted, not now. If ASC's own
+enforcement is in the way, the exit is \`asc mode manual\`.
+
+**A workspace whose mode cannot be read is not MANUAL.** If the record is there but broken,
+raw external writes stay blocked and \`asc status\` names the reason
+(\`MODE_STATE_UNREADABLE\` / \`MODE_STATE_INVALID\`). ASC's own commands still run, and that
+is how it gets fixed.
+
+## Whose decision is which
+
+\`\`\`text
+the project's rules   what has to be done, on which branch, in what order
+ASC                   who owns the work · what a person must decide · whether this
+                      action is executable against the remote right now · execution · audit
+\`\`\`
+
+ASC does not own a project's workflow. If a repository's own conventions say a branch is
+updated a certain way, that judgement belongs to those conventions — ASC checks that the
+action they chose is possible against the current remote, not whether it was the right
+action. A canonical source is what judgement is measured against; it is not a list of the
+only branches that may be written.
+
+## Maintenance — the same words in both products
+
+\`\`\`text
+"업데이트해"            → asc update       · jam update
+"적용 상태 다시 맞춰"    → asc refresh      · jam refresh
+"지금 상태 어때"         → asc status       · jam status
+"제거해"                → asc uninstall    · jam uninstall
+\`\`\`
+
+\`update\` moves to a new published version. \`refresh\` keeps the version and re-converges
+only what this runtime installed — it never re-infers the profile, the workspace, the
+identity or the bindings, and it never touches sessions. \`uninstall\` removes the product
+and leaves every bit of your state where it is.
+
 ## "Update ASC" — one command per product, no questions
 
 Each product updates itself. ASC never updates JAM and JAM never updates ASC; the person
@@ -160,9 +226,10 @@ report as one.
    - **Receiving a DECIDE creates no approval, authority or scope.** If a human decision is
      needed, use that answer as evidence and raise it to a person.
 
-5. Pausing: \`asc session pause <ID> --position "<how far>" --next "<next action>"\`.
-   Finishing: \`asc session done <ID> --verified "<what the self-check covered>" --next "<next>"\`.
-   Updating state is the Controller's job — point the person at \`asc controller collect\`.
+5. Pausing: \`asc work pause <S-ID> --position "<how far>" --next "<next action>"\`.
+   Finishing: \`asc work finish <S-ID> --verified "<what the self-check covered>" --next "<next>"\`.
+   One command finishes it: the handoff is written, the physical binding is released, the
+   Controller collects, and the session is archived. Do not make a person run two steps.
 
 ## "Publish it" — what a session produced, going out
 
@@ -170,14 +237,31 @@ The person says *publish it* · *open the MR* · *get it onto develop*. That sen
 approval, and it is not asked for twice. It is also not wider than itself: **"open the MR"
 is not "approve the merge"**.
 
-Nothing reaches an external system except through a grant. That is one command, then the
-act:
+Nothing reaches an external system except through an approved grant. One command carries
+that whole path — read-only review, decision authority, grant, atomic claim, revalidation,
+exactly one write, read-back, audit:
 
 \`\`\`text
-asc grant issue --session <S-ID> --action <key> --target <ref> --body-file <path> --as <actor>
-asc grant run <G-ID>
+asc work publish [<S-ID>] --action <key> --target <ref> --body-file <path> --as <actor>
+asc work publish … --review    # read the facts and stop. Nothing goes out
 \`\`\`
 
+The review is **not a second approval**. The person's instruction already settled who
+decides; the review settles facts — is this the remote this work is bound to, is the commit
+that was approved still the commit that is here, is there already an open change for it. A
+\`NOT_EXECUTABLE\` means the action does not hold as it stands; a \`REVIEW_REQUIRED\` means a
+person has to look at something the facts cannot settle. Neither is a request to re-approve.
+
+Afterwards the result is read back. If what comes back differs from what was expected the
+outcome is \`NOT_VERIFIED\` — the write happened, it is not a success, and the grant is
+spent either way. If the outcome could not be determined at all it is \`UNCERTAIN\`: read
+the remote before doing anything else, and never repeat the command.
+
+Being bound to one repository is the scope of managed execution, not a preference. If the
+target is a different repository the answer is \`REVIEW_REQUIRED\`, and approving the action
+again does not change it — what has to change is the binding, and that is a separate
+decision.
+
 The action key is the provider's (\`gitlab.mr.create\`, \`gitlab.note.create\`, \`git.push\`,
 \`coordination.publish\`, \`github.issue_comment.create\`). If nothing bound to this
 workspace can carry out that action, issuing **fails there** rather than after the person
@@ -190,8 +274,14 @@ Publishing a coordination question is the same shape — \`asc coordination publ
 <G-ID> --query <X-ID> …\`. Reading (\`coordination status\`, \`coordination observe\`) needs
 no grant.
 
-**Never** reach for \`git push\`, \`glab\`, or \`gh\` directly. The guard stops those, and
-being stopped is not a puzzle to solve — it means the act belongs in a grant.
+**Never** reach for \`git push\`, \`glab\`, or \`gh\` directly while the mode is AUTO. The
+guard stops those, and being stopped is not a puzzle to solve — it means the act belongs in
+\`asc work publish\`. ASC's own commands are never blocked by that guard, so the way out is
+always an asc command, never uninstalling the hook.
+
+In MANUAL the guard blocks none of it. It leaves one line saying the write is leaving the
+managed path and pointing at \`asc work publish --review\`; what to do about that is the
+person's call, and the project's rules are what answer it.
 
 ## Progress reporting
 
@@ -230,6 +320,12 @@ A change that gives a person no reason to look again is noise, not a report.
   portable command is the bootstrap one
 - Investigate external situations directly — leave reading thread originals to \`asc-inbox\` and take back only what it summarised
 - Declare that I verified what I built — independent verification is \`asc-review\`
+- Teach a person the internal order (session issue · host bind · grant issue · controller
+  collect). On a healthy path they type none of those — \`work start\`, \`work publish\`,
+  \`work finish\` cover it
+- Treat AUTO as permission, or MANUAL as approval. Neither mode decides what a person
+  must decide
+- Turn enforcement off by removing the product. \`asc mode manual\` is the exit
 `;
 }
 export function inboxSkillText() {

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

@@ -33,6 +33,7 @@ export declare class GlabApiClient implements GitLabReader, GitLabWriter {
     constructor(run: ProcessRunner);
     get<T>(path: string): Promise<GitLabResponse<T>>;
     post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
+    put<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
 }
 /**
  * 읽기 통로. GitLabClient(토큰)와 GlabApiClient(로그인된 도구) 둘 다 이것이다 —
@@ -50,6 +51,14 @@ export declare class GlabApiClient implements GitLabReader, GitLabWriter {
  */
 export interface GitLabWriter {
     post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
+    /**
+     * GitLab 의 merge 는 `PUT /merge_requests/:iid/merge` 다 (공식 계약).
+     *
+     * 예전에는 POST 로 보냈다. 그 경로는 승인이 끝난 뒤에 실패하고, 실패한 것이 정말 나가지
+     * 않았는지는 그 자리에서 알 수 없다 — 통로가 없는 것과 잘못된 통로로 부르는 것은 다르고,
+     * 후자가 더 나쁘다. 통로가 없으면 없다고 말할 수 있게 optional 로 둔다.
+     */
+    put?<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
 }
 export interface GitLabReader {
     get<T>(path: string): Promise<GitLabResponse<T>>;
@@ -59,6 +68,7 @@ export declare class GitLabClient implements GitLabReader, GitLabWriter {
     constructor(deps: GitLabClientDeps);
     get<T>(path: string): Promise<GitLabResponse<T>>;
     post<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
+    put<T>(path: string, body: Record<string, unknown>): Promise<GitLabResponse<T>>;
 }
 /** `group/sub/project!19` 또는 `group/project#7` 을 쪼갠다. */
 export declare function parseRef(reference: string): {

package/dist/adapters/gitlab/client.js

@@ -51,6 +51,16 @@ export class GlabApiClient {
             return { ok: false, status: 0, data: null, error: String(error.message ?? error).slice(0, 200) };
         }
     }
+    async put(path, body) {
+        const fields = Object.entries(body).flatMap(([key, value]) => value === undefined ? [] : ['-f', `${key}=${String(value)}`]);
+        try {
+            const stdout = await this.#run('glab', ['api', '--method', 'PUT', path.replace(/^\//, ''), ...fields]);
+            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;
@@ -78,8 +88,14 @@ export class GitLabClient {
         };
     }
     async post(path, body) {
+        return this.#write('POST', path, body);
+    }
+    async put(path, body) {
+        return this.#write('PUT', path, body);
+    }
+    async #write(method, path, body) {
         const response = await this.#fetch(`${this.#baseUrl}${path}`, {
-            method: 'POST',
+            method,
             headers: {
                 accept: 'application/json',
                 'content-type': 'application/json',

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

@@ -1,8 +1,16 @@
 import type { CanonicalSnapshot } from '../../core/model/entities.ts';
+import type { RemoteFacts } from '../../core/execution/remote-review.ts';
 import type { BaselineQuery, ExternalAction, ExternalActionResult, ScmPort, ThreadSnapshot } from '../../ports/scm.ts';
 import { type GitLabReader, type GitLabWriter } from './client.ts';
 /** 이 adapter 가 수행할 수 있는 행위. 목록에 없는 것은 하지 않는다. */
 export declare const GITLAB_ACTIONS: readonly ["coordination.publish", "gitlab.note.create", "gitlab.mr.create", "gitlab.mr.merge", "gitlab.issue.update", "git.push"];
+/**
+ * 되돌려 읽을 수 있는 행위 (0.8.0 보정 P1-2).
+ *
+ * `coordination.publish` 가 여기 없는 이유는 그 실행이 이 통로가 아니라 조율 표면에서
+ * 나가기 때문이다 — 자기가 하지 않은 일을 확인했다고 말하지 않는다.
+ */
+export declare const VERIFIABLE_ACTIONS: readonly ["git.push", "gitlab.mr.create", "gitlab.mr.merge", "gitlab.note.create", "gitlab.issue.update"];
 export type GitLabScmDeps = {
     reader: GitLabReader;
     writer: GitLabWriter;
@@ -14,6 +22,8 @@ export type GitLabScmDeps = {
     }>>;
     /** `git.push` 를 수행할 자리. 없으면 push 는 할 수 없다고 답한다. */
     repoRoot?: string;
+    /** 이 결합이 가리키는 원격 이름. 검수가 URL·신원을 읽을 자리다. */
+    remoteName?: string;
     /** 테스트가 실제 git 을 부르지 않게 하는 통로. */
     git?: (args: readonly string[], cwd: string) => Promise<{
         ok: boolean;
@@ -39,5 +49,26 @@ export declare class GitLabScm implements ScmPort {
      */
     /** 이 통로가 아는 행위. execute 의 분기와 같은 목록이어야 한다. */
     supports(action: string): boolean;
+    /**
+     * 나가기 **전에** 읽히는 사실 (0.8.0 §D·§L·§M·§N). 판정은 하지 않는다 — Core 의
+     * Remote Review 가 이 사실로 판정한다. 여기서 쓰는 것은 하나도 없다.
+     */
+    review(action: ExternalAction): Promise<RemoteFacts>;
+    /** 되돌려 읽을 수 있는 행위. `execute` 의 분기와 이 목록이 갈리면 그것이 결함이다. */
+    verifies(action: string): boolean;
+    /**
+     * 나간 **뒤에** 밖에서 읽히는 사실. 명령이 0 으로 끝났다는 것은 성공이 아니다.
+     */
+    verify(action: ExternalAction, result: {
+        resultRef: string;
+    }): Promise<{
+        observed: Record<string, string | undefined>;
+        unsupported?: boolean;
+    }>;
     execute(action: ExternalAction): Promise<ExternalActionResult>;
 }
+/**
+ * 원격 URL 에서 프로젝트 신원만 꺼낸다 — `git@host:group/p.git` 도 `https://host/group/p` 도
+ * 같은 `group/p` 다. 결합과 견주는 값이므로 형태가 아니라 신원이어야 한다.
+ */
+export declare function identityOf(url: string): string;