Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
13 changes: 7 additions & 6 deletions .issueops/ADR.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ and supersession rules live in [adr/README.md](adr/README.md).

| Date | Decision | Record |
|---|---|---|
| 2026-10-15 | Remove the Orca integration and execution mode selection: direct is the only execution, `execution prepare --id ID` takes no mode, the resume and mode-switch commands are deleted, and sessions hand off only through release, `execution replace --preview`, and `claim --claim-current-token`; supersedes in part the auto execution mode of 2026-09-05 and the Orca judgement of 2026-07-19 | [record](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) |
| 2026-10-14 | Entering pr seals the canonical HEAD as `pr_head`; `execution complete` refuses a final head that changed anything but the verification report since; re-running `phase --to pr` from pr passes the same strict gate and reseals | [record](adr/2026-10-14-completion-checks-the-verified-pr-head.md) |
| 2026-10-14 | `gates lint` / MCP `gates_lint` checks gate specs, plan gate lines, and ledgers without running them (spec rules, the command policy check would apply, markdown backticks, RE2 EXPECT); plans write gates as one-line specs and lint before staging; the author sweeps stale text, prescribed facts, and gates before each delta review | [record](adr/2026-10-14-gates-lint-and-pre-delta-author-sweep.md) |
| 2026-10-13 | The project-doc catalog carries a usage line (open the owning module; quote applied doc rules verbatim with their path), and `project_docs_route` returns up to three owning modules of routed index docs; extends the catalog format of 2026-10-08 | [record](adr/2026-10-13-catalog-usage-line-and-module-routing.md) |
Expand All @@ -45,7 +46,7 @@ and supersession rules live in [adr/README.md](adr/README.md).
| 2026-10-08 | State cleanup runs on the write path that owns it: `channel send` prunes 7-day-old messages, install/update removes retired state paths after commit, and the MCP HTTP log is capped in-process | [record](adr/2026-10-08-state-cleanup-runs-on-the-write-path-that-owns-it.md) |
| 2026-10-08 | omp (oh-my-pi) is the fourth first-party host; its lifecycle extension exports the main session id as `ISSUEOPS_OMP_SESSION_ID`; superseded in part — role models read the settings files since [2026-10-12](adr/2026-10-12-omp-role-models-resolve-from-the-agent-model-settings-files.md) | [record](adr/2026-10-08-omp-first-party-host.md) |
| 2026-10-08 | SubagentStart carries the project-doc catalog, and every host gets the same model text; supersedes the "SessionStart only" clause of 2026-08-27 | [record](adr/2026-10-08-subagent-start-catalog-and-unified-model-text.md) |
| 2026-10-08 | Role models resolve from flag, main-worktree local, and XDG global settings and are injected into Orca·cmux owner sessions; supersedes the Claude implement default of 2026-09-24; superseded in part — omo and omp also read the settings files since [2026-10-12](adr/2026-10-12-omp-role-models-resolve-from-the-agent-model-settings-files.md) | [record](adr/2026-10-08-role-models-resolve-from-global-and-local-settings-and-are-i.md) |
| 2026-10-08 | Role models resolve from flag, main-worktree local, and XDG global settings and are injected into Orca·cmux owner sessions; supersedes the Claude implement default of 2026-09-24; superseded in part — omo and omp also read the settings files since [2026-10-12](adr/2026-10-12-omp-role-models-resolve-from-the-agent-model-settings-files.md), and the Orca owner-session injection is gone since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-10-08-role-models-resolve-from-global-and-local-settings-and-are-i.md) |
| 2026-10-07 | Review revise and regress rounds are capped at five; supersedes the cap number of 2026-07-02 and 2026-09-08 Decision (4) | [record](adr/2026-10-07-review-revise-and-regress-rounds-are-capped-at-five.md) |
| 2026-10-07 | `.issueops` 폴더 구조를 append와 runtime이 쓰는 경로에 맞추고 checker가 강제한다 | [record](adr/2026-10-07-issueops-docs-layout-matches-the-append-and-runtime-paths.md) |
| 2026-10-07 | Readers accept only the current record shape | [record](adr/2026-10-07-readers-accept-only-the-current-record-shape.md) |
Expand All @@ -70,7 +71,7 @@ and supersession rules live in [adr/README.md](adr/README.md).
| 2026-09-08 | IssueOps project-doc gates: link-plan checks the four plan sections and no-change needs reviewed docs | [record](adr/2026-09-08-issueops-project-doc-gates-link-plan-checks-the-four-plan-se.md) |
| 2026-09-02 | IssueOps binds artifacts to the code project, not the issue project | [record](adr/2026-09-02-issueops-binds-artifacts-to-the-code-project-not-the-issue-p.md) |
| 2026-09-05 | IssueOps v0.1.0 이름 전환 | [record](adr/2026-09-05-issueops-v0-1-0.md) |
| 2026-09-05 | IssueOps ten-stage skills, CLI-owned stage detection, and the auto execution mode | [record](adr/2026-09-05-issueops-ten-stage-skills-with-auto-execution-mode.md) |
| 2026-09-05 | IssueOps ten-stage skills, CLI-owned stage detection, and the auto execution mode; superseded in part — the auto execution mode and the rejection of release + reseed as the handoff path are replaced since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-09-05-issueops-ten-stage-skills-with-auto-execution-mode.md) |
| 2026-09-02 | IssueOps publication evidence gates: project-doc reflection and conditional schema measurement | [record](adr/2026-09-02-issueops-publication-evidence-gates-project-doc-reflection-a.md) |
| 2026-08-28 | IssueOps devil's-advocate verdicts are bound to the reviewed plan digest | [record](adr/2026-08-28-issueops-devils-advocate-plan-binding.md) |
| 2026-08-28 | Optional upstream provisioning preserves the standalone core; partially supersedes the 2026-07-07 blanket prohibition | [record](adr/2026-08-28-optional-upstream-provisioning-preserves-the-standalone-core.md) |
Expand All @@ -89,13 +90,13 @@ and supersession rules live in [adr/README.md](adr/README.md).
| 2026-07-29 | Release vertical replaces the lease prototype | [record](adr/2026-07-29-release-vertical-replaces-lease-prototype.md) |
| 2026-07-28 | Lease differential contract owns stable v1 canonicalization; superseded on 2026-09-23 | [record](adr/2026-07-28-lease-differential-v1-canonicalization.md) |
| 2026-07-27 | Architecture dependency fitness ratchet | [record](adr/2026-07-27-architecture-dependency-fitness-ratchet.md) |
| 2026-07-26 | Linked branches are pinned to the sealed base SHA | [record](adr/2026-07-26-linked-branches-pinned-to-sealed-base-sha.md) |
| 2026-07-24 | IssueOps planner/implementer dual structure (#78) | [record](adr/2026-07-24-issueops-planner-implementer-dual-structure.md) |
| 2026-07-26 | Linked branches are pinned to the sealed base SHA; superseded in part — the Orca-before-linking order is gone since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-07-26-linked-branches-pinned-to-sealed-base-sha.md) |
| 2026-07-24 | IssueOps planner/implementer dual structure (#78); superseded in part — the Orca owner packet seal and orca-to-git cleanup order are gone since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-07-24-issueops-planner-implementer-dual-structure.md) |
| 2026-07-24 | Canonical command with managed `io` shorthand | [record](adr/2026-07-24-canonical-command-io-shorthand.md) |
| 2026-07-24 | Workpool removal | [record](adr/2026-07-24-workpool-removal.md) |
| 2026-07-21 | IssueOps uses one ownership handoff contract | [record](adr/2026-07-21-issueops-ownership-handoff-contract.md) |
| 2026-07-19 | One operational-health authority and external one-time reconciliation | [record](adr/2026-07-19-operational-health-authority-and-external-reconciliation.md) |
| 2026-07-15 | Supervised handoff coordinator isolation and bounded self-heal | [record](adr/2026-07-15-supervised-handoff-coordinator-isolation.md) |
| 2026-07-19 | One operational-health authority and external one-time reconciliation; superseded in part — `doctor` no longer judges Orca since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-07-19-operational-health-authority-and-external-reconciliation.md) |
| 2026-07-15 | Supervised handoff coordinator isolation and bounded self-heal; superseded in part — the Orca terminal handle routing is gone since [2026-10-15](adr/2026-10-15-remove-orca-integration-and-execution-mode-selection.md) | [record](adr/2026-07-15-supervised-handoff-coordinator-isolation.md) |
| 2026-07-14 | Evidence-first cross-host tool contract hardening | [record](adr/2026-07-14-evidence-first-cross-host-tool-contract.md) |
| 2026-07-09 | Pipe-capture immunity and pipe-capacity doctor check | [record](adr/2026-07-09-pipe-capture-immunity-doctor-check.md) |
| 2026-07-09 | Loop contracts | [record](adr/2026-07-09-loop-contracts.md) |
Expand Down
51 changes: 21 additions & 30 deletions .issueops/AGENT_WORKFLOW.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,12 +27,13 @@ description: Agent start, execution, verification, and completion flow; read whe
## IssueOps 자동 세션 인계

전체 사이클은 `skills/issueops/SKILL.md`의 환경별 자동 세션 인계를 따른다. 일반 흐름은
이슈 확정·계획·리뷰 뒤 `execution prepare --mode direct`와 사유를 사용해 canonical
worktree를 준비한다. 준비 세션이 Herdr 세션이면 Herdr를 먼저 확인해 사용 가능하면 Orca가
ready여도 Herdr로 인계한다. 그 밖에는 Orca runtime이 ready면 같은 worktree의 새 세션으로 자동 인계한다.
Orca가 없거나 unready면 Herdr의 실행 중인 서버·호환성·현재 native host 실행 가능 여부를
확인해 새 세션으로 인계하고, 둘 다 사용 불가면 현재 세션에서 이어간다.
실행 방식 메뉴나 진행 여부를 묻지 않는다. Herdr는 준비된 worktree를 열며 재생성하지 않는다.
이슈 확정·계획·리뷰 뒤 `execution prepare --id ID $ACTOR_FLAGS`로 preview를 확인하고
`--confirm`으로 canonical worktree를 준비한다. 브랜치와 worktree를 준비한 뒤 Herdr를 확인한다.
Herdr 세션에서 준비 중이고 실행 중인 서버·호환성·현재 native host 실행 가능 여부가 확인되면
같은 worktree의 새 Herdr 세션으로 인계한다. Herdr를 쓸 수 없으면 현재 세션에서 이어가거나,
사용자가 직접 연 두 번째 터미널에서 수동으로 인계한다. 바이너리 설치 여부만으로 Herdr가 준비되었다고
판단하지 않으며, 런처를 설치하거나 서버를 시작하지 않는다. 실행 방식 메뉴나 진행 여부를 묻지 않는다.
cmux는 사용자가 명시적으로 선택할 때만 쓴다. Herdr는 준비된 worktree를 열며 재생성하지 않는다.

자동 결정은 원래 요청의 승인 범위·종료점을 유지한다. 환경 관찰값·원래 사용자 요청·
대화 근거·ID·경로·범위·종료점을 기존 decision record에 남긴다.
Expand Down Expand Up @@ -75,9 +76,9 @@ IssueOps에서 authority는 `issueops ...` CLI/MCP 하나다. 이 경로가 dura

`issueops execution prepare`를 confirm한 뒤에는 반환된 canonical path를 `ISSUEOPS_EXPECTED_WORKTREE`에 반영한다. 이후 편집은 그 절대경로, `git -C "$ISSUEOPS_EXPECTED_WORKTREE"`, worktree-rooted CodeGraph/`rg`/test 명령으로 수행하고, source checkout과 worktree의 `git status --short`를 따로 확인한다.

선택적 Orca 실행은 `issueops execution prepare --mode auto|direct|orca`로 선택한다. Preview와 confirm 요청은 `--confirm` 외에는 동일해야 한다. Orca가 첫 external mutation 전에 absent/unready이면 `auto`는 direct를 선택한다. Orca가 선택되면 private issue/context packet과 fully rendered prompt를 봉인하고 fresh native owner를 launch한다. Owner는 status가 렌더한 `issueops execution claim --claim-current-token` 명령에서 두 digest를 검증한 뒤에만 쓴다. CLI가 현재 generation의 private token path를 내부에서 결정하므로 token path나 값은 owner prompt에 넣지 않는다. 외부 mutation 전에는 pending intent를 durable state에 먼저 저장하며, 모호한 결과는 create를 재시도하거나 direct로 전환하지 않고 `issueops execution reconcile`로 정확히 하나의 결과를 확인한다. 구현, 검증, generation-fenced PR/MR 생성, `issueops execution complete`는 active holder가 canonical worktree에서 수행한다. Complete는 `done`과 lease release를 원자적으로 기록하며 merge와 cleanup은 하지 않는다.
`issueops execution prepare`의 preview와 confirm 요청은 `--confirm` 외에는 동일해야 한다. 외부 mutation 전에는 pending intent를 durable state에 먼저 저장하며, 모호한 결과는 create를 재시도하지 않고 `issueops execution reconcile`로 정확히 하나의 결과를 확인한다. 구현, 검증, generation-fenced PR/MR 생성, `issueops execution complete`는 active holder가 canonical worktree에서 수행한다. Complete는 `done`과 lease release를 원자적으로 기록하며 merge와 cleanup은 하지 않는다.

완료된 execution을 새 generation과 새 HEAD로 복구할 때는 status/preview가 제공한 typed reseed만 사용한다. Completion-bearing reseed는 이전 영수증을 append-only `completion_history`로 보존하고 current completion, done phase, HEAD-bound proof를 같은 CAS에서 재개 상태로 바꾼다. Completion receipt는 generation을 직접 stamp하며, generation이 없는 receipt를 담은 레코드는 읽을 때 거부된다. `--completion-generation N`은 stamp된 generation과 같아야 하고 preview와 reseed에 동일하게 전달한다. 누락·충돌은 mutation 전에 fail-closed한다. 새 owner는 status의 exact `resume`/`claim`을 실행하고 `implement`부터 AI-slop, implementation review, `pr`, completion까지 정상 순방향 gate를 다시 통과한다. History는 감사 기록이지 현재 generation의 retry evidence가 아니며 state 파일 수동 편집으로 제거하지 않는다.
완료된 execution을 새 generation과 새 HEAD로 복구할 때는 status/preview가 제공한 typed reseed만 사용한다. Completion-bearing reseed는 이전 영수증을 append-only `completion_history`로 보존하고 current completion, done phase, HEAD-bound proof를 같은 CAS에서 재개 상태로 바꾼다. Completion receipt는 generation을 직접 stamp하며, generation이 없는 receipt를 담은 레코드는 읽을 때 거부된다. `--completion-generation N`은 stamp된 generation과 같아야 하고 preview와 reseed에 동일하게 전달한다. 누락·충돌은 mutation 전에 fail-closed한다. 새 holder는 status의 exact `claim`을 실행하고 `implement`부터 AI-slop, implementation review, `pr`, completion까지 정상 순방향 gate를 다시 통과한다. History는 감사 기록이지 현재 generation의 retry evidence가 아니며 state 파일 수동 편집으로 제거하지 않는다.

Delegated child cycle은 parent plan/evidence가 sub-agent pattern slug, 기대 이득, tradeoff, fallback, verification을 기록한 뒤에만 시작한다. Parent와 child가 같은 repo를 보더라도 각자의 exact lifecycle ID, execution generation, native actor, canonical worktree가 분리되어야 한다. Child는 자기 worktree와 execution lease 안에서만 작업하고, parent main agent가 결과를 검증해 accept/reject를 기록한다.

Expand Down Expand Up @@ -126,42 +127,32 @@ phase 진입은 fail-closed다: `grill` 진입은 problem 완료(`intent_contrac
## Execution v1 workflow

After the provider-linked branch and exact base SHA are recorded, preview and
confirm `issueops execution prepare --mode direct --direct-reason "<automatic session handoff reason>"`
for the ordinary flow, then apply the environment-based automatic session handoff. An explicitly requested GitHub Orca execution is the exception:
record the matching provider/issue identity and exact base SHA first, prepare
the local-only Orca branch, then create and record the linked branch before
plan linkage and implementation. Direct mode grants the calling native session
generation 1; Orca mode launches one owner that verifies the sealed
issue/context digests and asks the CLI to consume the current-generation private token.
confirm `issueops execution prepare --id ID $ACTOR_FLAGS` (add `--confirm` to
create), then apply the environment-based automatic session handoff. The
preview shows the workspace root, branch, and base. The calling native session
is granted generation 1. Handoff to another session uses only the takeover
chain: the current holder runs `release`, the new session runs
`execution replace --id ID --expected-generation N --preview` with its own
native actor, then the returned `--reseed` command, then
`claim --claim-current-token`.
The active holder performs implementation, cleanup, project-doc reflection,
verification, publication, and completion from the canonical worktree; planning
happens before the lease exists, in the preparing session. The source main worktree remains
available before, during, and after execution for unrelated work.

GitLab-linked execution은 특정 MCP server 이름이 아니라 semantic leaf
`glab_api`와 실제 schema로 snapshot capability를 찾는다. 개인 wrapper도 같은
leaf와 compatible schema를 노출하면 후보가 된다. `web_url`, `description`,
`state`를 linked authority/project/IID와 대조한 뒤 MCP에는 host-neutral
`issue_snapshot`을, CLI에는 exact mode `0600` file과
`--issue-snapshot-file`을 넘긴다. 후보 부재나 호출 실패 뒤 successful
exact-identity MCP evidence가 없을 때만 인자를 생략해 generic `glab api`
fallback을 사용한다. 이미 공급한 invalid evidence는 fallback하지 않는다. 성공 결과의
`issue_snapshot_source`가 `glab_mcp` 또는 `glab_cli`인지 확인한다.

Do not use source CWD or a generic session binding as a fence. Select the exact
lifecycle ID, generation, native process receipt, canonical worktree, and
persisted Orca resource. One active execution exists per record, so unrelated
lifecycle ID, generation, native process receipt, and canonical worktree.
One active execution exists per record, so unrelated
cycles remain independent. Completion records `done` and releases the lease;
merge and destructive cleanup require separate authority.

## 10단계 흐름 요약

1·2단계는 source checkout의 준비 세션이 `issueops-create-issue`와 `issueops-prepare`로
수행하며 lease를 갖지 않는다. 3단계 `issueops-plan`도 같은 세션이 수행하고,
`execution prepare --mode direct`로 워크트리를 준비한 뒤 위 자동 세션 인계를 따른다.
Herdr 세션이면 Herdr를 먼저, 그 밖에는 Orca, Herdr 순서로 사용 가능 여부를 확인하며 둘 다 사용 불가면 현재 세션에서 이어간다.
`execution prepare --id ID $ACTOR_FLAGS`로 워크트리를 준비한 뒤 위 자동 세션 인계를 따른다.
Herdr 세션이면 Herdr를 먼저 확인하고, Herdr를 쓸 수 없으면 현재 세션에서 이어가거나 사용자가 직접 연 두 번째 터미널에서 수동 인계한다.
실행 방식은 묻지 않으며 새 세션은 같은 worktree의 release·인수 절차를 사용한다.
명시적으로 요청한 Orca execution과 기존 사이클은 해당 core 경로를 유지한다.
4단계부터는 구현 세션이 canonical worktree에서 `issueops-implement` → `issueops-slop-clean` →
`issueops-docs` → `issueops-verify` → `atomic-commit-push` → `issueops-create-pr` →
`issueops-complete`를 지나 완료한다. 개발자가 PR을 확인하면 메인 세션의 `issueops-merge`가
Expand Down
Loading
Loading