@bluenyang/reins 0.0.0-stage → 0.1.0

package/docs/README.ko.md

@@ -0,0 +1,151 @@
+# reins
+
+[English](../README.md)
+
+reins는 저장소에 에이전트 하네스를 설치하고 기존 하네스를 옮기고 갱신하는 도구입니다. 하네스는 코딩
+에이전트의 역할, 루프 정책, 스키마로 검증되는 인수인계 파일, 지식 저장소, 게이트로 이루어집니다.
+정해진 지점마다 스크립트 `reins check`가 루프를 계속해도 되는지 판정하므로 에이전트는 자기 역할
+안에서 지시받은 일만 합니다. 사람은 게이트에서 결정만 내립니다.
+
+BlueNyang과 Team Croffle의 저장소 열두 곳이 같은 하네스 계보를 쓰면서 같은 문제를 겪고 있어 이
+도구를 만듭니다. 에이전트가 요청 밖으로 나가고 구현한 세션이 검증과 판단까지 합니다. 지식이 gitignore
+영역에서 사라지고 멈추는 기준이 없습니다. 복사본끼리 어긋나고 루프가 Claude에서만 돕니다. 문제 전체
+목록(P1–P6)은 [proposal.ko.md](proposal.ko.md)에 있습니다.
+
+## 상태
+
+버전 0.1.0은 프리릴리스이며 계획의 1차(round one)입니다. 아직 npm에 올라가 있지 않고 Claude Code
+플러그인 매니페스트도 없습니다. 그래서 지금은 `npx @bluenyang/reins`가 동작하지 않으니 소스에서
+빌드해야 합니다([소스에서 시작하기](#소스에서-시작하기) 참고). 생성되는 벤더 파일은 Claude Code만
+검증했습니다.
+
+reins는 자기 루프로 자기 자신을 개발합니다. intent 001(`reins status`)은 intent → spec → plan →
+ticket 순서를 거쳤고 T1~T5 검사를 통과했으며 코드 리뷰는 Codex가 맡았습니다. 이때 다른 벤더에 묶인
+역할은 각 벤더 CLI(`codex exec`, `agy -p`)로 돌았습니다. `reins-loop` 스킬에 따라 주 에이전트가
+호출한 것이며 CLI가 벤더를 스스로 부르는 기능은 아직 없습니다.
+
+## 사다리
+
+단계는 세 가지입니다. 위 단계는 아래 단계를 포함하고 세 단계는 하나의 원본을 공유합니다.
+
+| 단계 | 구성 |
+|---|---|
+| harness | 커밋·푸시 시점의 검증기(T2, T4, T6), 레드라인, 생성되는 권한 설정 |
+| loop | 계획 → 작업 → 테스트 → 릴리스 사이클, 역할 수는 줄고 전환 지점과 정지 조건은 같습니다 |
+| graph | 열두 역할 전부, 스키마로 검증되는 인수인계 파일, 역할별 모델 바인딩 |
+
+`reins install <tier>`는 세 단계 모두 받습니다. 1차는 graph 단계를 겨냥합니다. 0.2에서는 측정한 비용을
+입력으로 삼아 graph에서 loop와 harness를 깎아 낼 계획입니다.
+
+## 동작 방식
+
+**역할.** 열두 개입니다: pm, planner, pl, implementer, lookup, verify-tool, code-review, qa-design,
+qa-run, deploy, docs, advisor. 역할 파일마다 해서는 안 되는 일이 적혀 있습니다. 역할을 나누는 것이
+모델을 나누는 것은 아닙니다. 모든 역할을 한 모델로 돌릴 수 있고 `bindings.yaml`이 역할마다 벤더와
+모델을 정합니다. 설계상 감지되지 않은 벤더에 묶인 역할은 fallback으로, 그것도 없으면 pm의 모델로
+돌아가므로 열두 역할 모두 Claude만으로 돌 수 있습니다.
+
+**레드라인.** 모든 역할에 적용되고 검증기가 강제하는 규칙이 열 개(C1–C10) 있습니다. 몇 가지를 들면
+이렇습니다. 통과만 시키는 구현 금지(C1), 관리 블록·정책·역할 파일 수정 금지(C2), 자기 권한 파일 수정
+금지(C3), 시크릿 읽기 금지(C4), 훅 우회 금지(C5), deploy 역할 밖의 push·PR·merge·릴리스 금지(C6).
+전체 목록은 [design.ko.md](design.ko.md) 2절에 있습니다.
+
+**검증기.** `reins check`는 전환 지점마다 돌아 판정을 하나 출력합니다. 모델을 호출하지 않습니다.
+역할이 판단을 인수인계 파일에 쓰면 검증기가 그것을 적용할 뿐입니다.
+
+| 판정 | 종료 코드 | 의미 |
+|---|---|---|
+| CONTINUE | 0 | 계속 진행 |
+| HOLD | 10 | 사용자의 답이 필요합니다 |
+| STOP | 20 | 사람 없이 고칠 수 있고 이어서 재개합니다. 정지할 때 어디서, 왜(A1~G2 중 id), 어떻게 재개하는지 기록합니다 |
+| ESCALATE | 30 | 실패 사슬: pl → pm → advisor → 사용자 |
+
+정지 조건 A1–G2는 24개이며 되돌릴 수 없는 작업, 미결 결정, 무너진 전제, 반복 실패, 비용, 규칙 위반,
+사용자 중단을 다룹니다.
+
+**사슬과 사람의 두 결정.** 작업은 `intent.md` → `spec.md` → `plan.md` → ticket 네 파일을 따라
+흐릅니다. 사람이 결정하는 지점은 둘입니다. intent는 사용자가 승인하고 spec은 3~5줄 요약을 보고
+사용자가 거부할 수 있습니다. 나머지는 역할끼리 검토합니다. 검증 출력은 나온 그대로 붙입니다.
+"통과"라는 한 마디만으로는 통과가 아닙니다.
+
+**배치.**
+
+| 경로 | 커밋 | 내용 |
+|---|---|---|
+| `AGENTS.md` | 합니다 | 도구가 쓰는 관리 블록, 프로젝트가 쓰는 섹션 |
+| `.agents/` | 합니다 | `intent/`, `knowledge/`, `harness/`(역할, 정책, 스키마, 템플릿, `bindings.yaml`, `gates.yaml`), `skills/` |
+| `.claude/` | 합니다 | `.agents/`에서 생성한 파일, 직접 고치지 않습니다 |
+| `.loctx/` | 안 합니다 (gitignore) | ticket, 보고서, 인수인계 `bus/`, `history/`, 로컬 로드맵 |
+
+## 소스에서 시작하기
+
+Node 20 이상과 pnpm이 필요합니다.
+
+```sh
+git clone https://github.com/bluenyang/reins.git
+cd reins
+pnpm install
+pnpm build
+```
+
+CLI는 설치하려는 저장소의 루트에서 실행합니다. 저장소에 커밋이 하나 이상 있어야 합니다(0.1.0의
+`check`는 커밋이 없는 저장소에서 실패합니다).
+
+```sh
+node /path/to/reins/cli/dist/reins.js install graph --dry-run   # 쓸 파일을 미리 보여 줍니다
+node /path/to/reins/cli/dist/reins.js install graph --mode auto # 파일을 놓고 CLI를 감지해 기본값을 적용합니다
+node /path/to/reins/cli/dist/reins.js check --drift             # 원본과 생성물이 맞으면 "drift: ok"를 출력합니다
+node /path/to/reins/cli/dist/reins.js status                    # intent, ticket, bus, 마지막 history
+```
+
+3·4세대 하네스가 있는 저장소에는 `install`이 거부하고 `migrate`를 안내합니다. 훅은 설치 안내문에서
+제안만 하고 `--hooks`를 줄 때만 추가합니다. 배포되면 같은 명령을 `npx @bluenyang/reins <command>`로
+실행하게 할 계획입니다.
+
+## 명령
+
+| 명령 | 상태 | 하는 일 |
+|---|---|---|
+| `install <harness\|loop\|graph>` | 구현됨 | 하네스를 설치합니다. `--mode manual\|auto`, `--hooks`, `--dry-run`, `--json` |
+| `migrate <tier>` | 구현됨 | 기존 하네스나 `.ai/` 작업 공간을 이 배치로 옮깁니다 |
+| `update` | 구현됨 | 패키지된 하네스를 다시 적용하되 프로젝트 섹션은 건드리지 않습니다 |
+| `configure bindings` | 구현됨 | `--set role=model ...` 또는 `--vendors claude,openai`. 옵션이 없으면 묻습니다 |
+| `gate [names...]` | 구현됨 | `gates.yaml`을 선언된 대로 실행하고 원본 출력을 `.loctx/reports/`에 남깁니다 |
+| `status` | 구현됨 | 하네스, intent, ticket, bus, 마지막 history를 읽기 전용으로 보여 줍니다 |
+| `check` | 구현됨 | `--stage ticket-start\|pre-commit\|verdict\|pre-push\|rc-close` 또는 `--drift` |
+| `metrics` | 구현됨 | `.loctx/reports/metrics.jsonl` 요약: 역할·벤더·ticket·intent별 토큰, ticket당 knowledge 정지 수. `metrics record`로 역할 실행의 토큰을 남깁니다 |
+| `recall` | 미구현 | 증상으로 과거 결정을 찾습니다 |
+| `doctor` | 미구현 | — |
+| `configure budget\|gates\|language` | 미구현 | — |
+
+`install`, `migrate`, `update`, `gate`, `status`, `check`, `metrics`는 `--json`을 받습니다. `check`와 `gate`는 실행할 때마다 `.loctx/reports/metrics.jsonl`에 한 줄을 남깁니다. `check`의 stage는
+T1(`ticket-start`), T2(`pre-commit`), T3(`verdict`), T4(`pre-push`), T5(`rc-close`)에 대응합니다.
+
+## 스킬
+
+에이전트가 쓰는 진입점 스킬이 세 개 있고 `SKILL.md` 표준을 따릅니다.
+
+| 스킬 | 쓸 때 |
+|---|---|
+| `reins-setup` | reins를 설치하거나 기존 하네스를 옮길 때 |
+| `reins-intent` | 새 요청이 들어올 때: 질문지, 승인된 intent, 수락된 spec |
+| `reins-loop` | spec이 수락됐을 때: plan, ticket, 구현, 검증, 리뷰, history |
+
+## 로드맵
+
+| 버전 | 내용 |
+|---|---|
+| 0.1 | graph 설계, 이 저장소의 자기 설치·자기 이전, 검증기, 스킬 세 개, README. 0.1.0을 npm에 배포합니다 |
+| 0.2 | graph에서 loop·harness 깎기, Codex·Gemini·Cursor 생성물, `recall`·`doctor`·예산 정지, 이전 세대 하네스 시험 이전 |
+| 0.3 | Claude Code 플러그인, Team Croffle 저장소에 적용 |
+| 1.0 | 정해진 일정은 없습니다. 0.x에서 기능을 더해 가다가 메인테이너가 체계가 잡혔다고 판단할 때 1.0이 됩니다. 안정화만으로 1.0이 되지는 않습니다 |
+
+## 문서
+
+- [proposal.ko.md](proposal.ko.md): 문제, 목표, 요구사항, 성공 기준
+- [design.ko.md](design.ko.md): 배치, 역할, 정지 조건, 파일 형식, CLI
+- 영문판: [proposal.md](proposal.md), [design.md](design.md). 영문판과 한국어판이 다르면 한국어 파일이 우선합니다.
+
+## 라이선스
+
+MIT

package/harness/CHANGELOG.md

@@ -0,0 +1,10 @@
+# reins harness changelog
+
+Read by `reins update`: it lists the entries newer than a project's pinned version. An entry tagged
+`[skill]` needs the project's own sections touched — `reins update` then points to `/reins-update`,
+where the PM proposes those changes for the user to approve.
+
+## 0.1.0
+- First harness: twelve roles, red lines C1–C10, stop conditions A1–G2, schemas, templates, Node knowledge seeds.
+- Workflow block: committing each finished unit as you go is part of the work.
+- verify-tool runs gates through `reins gate` and cites its report files as evidence; `reins check` gains ticket-start (T1), verdict (T3) and rc-close (T5).

package/harness/VERSION

@@ -0,0 +1 @@
+0.1.0

package/harness/knowledge-seeds/node/2026-10-25_frozen-lockfile.md

@@ -0,0 +1,24 @@
+---
+id: 2026-10-25_frozen-lockfile
+kind: failure
+status: active
+supersedes: null
+topics: [install, lockfile, ci]
+decisions: []
+symptoms: ["ERR_PNPM_OUTDATED_LOCKFILE", "The lockfile would have been modified by this install", "YN0028"]
+applies_to: all
+source: preset
+symptom: "ERR_PNPM_OUTDATED_LOCKFILE | The lockfile would have been modified by this install"
+cause: package.json changed without updating the lockfile
+fix: run the package manager install locally and commit the lockfile with the change
+check: "<pm> install --frozen-lockfile (yarn: yarn install --immutable)"
+verified: 0
+---
+## 결정
+lockfile은 package.json과 같은 커밋에서 바뀐다.
+## 이유
+CI의 frozen install이 어긋난 lockfile을 거부한다.
+## 적용
+pnpm·yarn·npm 전부.
+## 바뀌면
+패키지 매니저를 바꾸면 `check` 명령을 갱신한다.

package/harness/knowledge-seeds/node/2026-10-25_mutating-lint-is-not-a-gate.md

@@ -0,0 +1,19 @@
+---
+id: 2026-10-25_mutating-lint-is-not-a-gate
+kind: decision
+status: active
+supersedes: null
+topics: [gates, lint, format]
+decisions: [mutating-lint-excluded]
+symptoms: ["lint passed but files changed", "format script rewrote files during the gate"]
+applies_to: all
+source: preset
+---
+## 결정
+파일을 수정하는 명령(`lint --fix`, `format --write`)은 게이트가 될 수 없다. 검사 전용 변형(`lint:check`, `format:check`)만 게이트다.
+## 이유
+게이트는 판정이어야 한다. 수정형 명령은 통과 여부와 무관하게 트리를 바꿔 커밋 내용을 흐린다 (조사: pipit-bot `lint --fix` 사고).
+## 적용
+`gates.yaml` `mutating_forbidden: true`. PM의 게이트 발견 절차가 수정형을 제외한다.
+## 바뀌면
+없음.

package/harness/policy/budget.yaml

@@ -0,0 +1,13 @@
+schema: reins/policy/budget@1
+# Token budgets (design §3). The narrowest scope in effect wins; a scope with no value only warns.
+unit: tokens
+scopes:            # shipped scopes; a project may add its own
+  - { name: project, set_by: install, stored_in: this file }
+  - { name: version, set_by: pm, stored_in: intent/<id>/plan.md }
+  - { name: rc, set_by: user|pm, stored_in: .loctx/history }
+  - { name: ticket, set_by: pl, stored_in: ticket frontmatter }
+  - { name: session, set_by: user, stored_in: .loctx/context }
+  - { name: role, set_by: user, stored_in: harness/bindings }
+precedence: [ticket, rc, version, project]   # role caps apply in addition
+warn_at: 0.8
+defaults: {}       # empty until measured on first use (R49)

package/harness/policy/common-red-lines.yaml

@@ -0,0 +1,25 @@
+schema: reins/policy/red-lines@1
+# Common prohibitions for every role (design §2). The verifier enforces these; roles add their own must_not.
+rules:
+  - id: C1
+    text: Implementing "to pass" — hard-coding, or making only some paths look right. Fix the cause.
+  - id: C2
+    text: Editing AGENTS.md managed blocks, harness/policy/ or harness/roles/ (pm and `reins update` only).
+  - id: C3
+    text: Editing one's own permission file or any generated vendor file.
+  - id: C4
+    text: Reading secret files.
+    patterns: ['.env', '.env.*', 'secrets/**', '*.key', '*.pem', '*.p12', '*.pfx', '*.properties', 'id_rsa', 'id_rsa.*', 'id_ed25519', 'id_ed25519.*']
+    allowed: ['.env.example', '*.example', '*.example.*', '*.sample']
+  - id: C5
+    text: Bypassing hooks (--no-verify) or massaging gate output (pipes that hide the exit code).
+  - id: C6
+    text: push, PR, merge, release, tag — deploy role only, inside the pre-release loop.
+  - id: C7
+    text: Reversing a recorded decision (knowledge/) without the user.
+  - id: C8
+    text: Re-raising a proposal the user rejected.
+  - id: C9
+    text: Touching running servers, clusters or network devices.
+  - id: C10
+    text: Changing files or behaviour outside the intent and plan — open a ticket instead.

package/harness/policy/stops.yaml

@@ -0,0 +1,29 @@
+schema: reins/policy/stops@1
+# Stop conditions (design §3). grade: HOLD needs the user · STOP resumable · ESCALATE follows the chain · WARN reports only (E1).
+# kind: intent = a person's call, never automated · knowledge = learned away over time.
+# Counters (D1, D2) reset when the unit passes.
+stops:
+  - { id: A1, group: irreversible, kind: intent, grade: HOLD, detect: verifier, text: "force push to a shared branch, deleting or moving a published tag, rewriting main", resume: "the user runs it explicitly, every time" }
+  - { id: A2, group: irreversible, kind: intent, grade: HOLD, detect: verifier, text: "stable (non-rc) release", resume: "the user's explicit instruction, every time" }
+  - { id: A3, group: irreversible, kind: intent, grade: HOLD, detect: verifier, text: "irreversible data change; touching running servers or clusters", resume: "the user's explicit instruction" }
+  - { id: A4, group: irreversible, kind: intent, grade: HOLD, detect: verifier, text: "anything leaving the machine outside the pre-release loop's defined steps", resume: "the user's instruction at that moment" }
+  - { id: B1, group: decision, kind: intent, grade: HOLD, detect: verifier, text: "a ticket with open asks:", resume: "record the answer in the ticket" }
+  - { id: B2, group: decision, kind: intent, grade: HOLD, detect: verifier, text: "a design invariant changes without a recorded decision", resume: "add the decision to knowledge/" }
+  - { id: B3, group: decision, kind: intent, grade: HOLD, detect: role, text: "a change conflicts with intent or spec (scope)", resume: "amend the intent or open a new one" }
+  - { id: B4, group: decision, kind: intent, grade: HOLD, detect: role, text: "the roadmap is silent or contradicts itself", resume: "fix the roadmap" }
+  - { id: B5, group: decision, kind: intent, grade: STOP, detect: role, text: "an external API or environment contradicts a design assumption and the scope changes", resume: "update spec.md, then HOLD for the user" }
+  - { id: C1, group: premise, kind: knowledge, grade: STOP, detect: role, text: "the rationale for the work no longer holds", resume: "fix plan.md and the ticket first, then continue" }
+  - { id: C2, group: premise, kind: knowledge, grade: STOP, detect: verifier, text: "the diff departs from plan.md and the plan was not updated (R45)", resume: "update plan.md in the same commit" }
+  - { id: D1, group: failure, kind: knowledge, grade: ESCALATE, detect: verifier, text: "two failed test rounds in the same unit (ticket before rc.1, rc after)", resume: "root cause by the next role in the chain" }
+  - { id: D2, group: failure, kind: knowledge, grade: ESCALATE, detect: verifier, text: "a red check twice with no fix in history or knowledge", resume: "root cause by the next role in the chain" }
+  - { id: D3, group: failure, kind: knowledge, grade: STOP, detect: verifier, text: "flaky: passes alone, fails in the full run", resume: "isolate the scenario, mark flaky in the report, continue, report to the user" }
+  - { id: D4, group: failure, kind: knowledge, grade: STOP, detect: verifier, text: "a suspected false pass: no exit code, empty output, piped gate", resume: "re-run the gate unmodified" }
+  - { id: D5, group: failure, kind: knowledge, grade: STOP, detect: verifier, text: "a pass row without toolchain evidence (R46)", resume: "attach the raw output" }
+  - { id: E1, group: cost, kind: knowledge, grade: WARN, detect: verifier, text: "80% of the narrowest budget in scope — warning only, continue", resume: "none" }
+  - { id: E2, group: cost, kind: knowledge, grade: STOP, detect: verifier, text: "100% of a ticket/scope budget", resume: "pm re-sets the budget, or HOLD" }
+  - { id: E3, group: cost, kind: knowledge, grade: HOLD, detect: verifier, text: "100% of an rc or session budget", resume: "the user" }
+  - { id: F1, group: violation, kind: knowledge, grade: STOP, detect: verifier, text: "a role attempts an action on its must_not list or a common red line", resume: "reassign the role or ask the user" }
+  - { id: F2, group: violation, kind: knowledge, grade: STOP, detect: drift-check, text: "drift between harness sources and generated files, or a convention violation", resume: "reins update / reins configure, then re-run the check" }
+  - { id: F3, group: violation, kind: knowledge, grade: STOP, detect: role, text: "a rejected proposal re-raised (C8)", resume: "drop it; record in knowledge/" }
+  - { id: G1, group: interrupt, kind: intent, grade: STOP, detect: runtime, text: "the user interrupts: chat, Ctrl+C, or session end (R48)", resume: "record ticket, stage, last commit, open bus files, next command; the same command resumes" }
+  - { id: G2, group: interrupt, kind: intent, grade: HOLD, detect: pm, text: "the user vetoes a spec summary (R64)", resume: "revise spec.md" }

package/harness/policy/transitions.yaml

@@ -0,0 +1,13 @@
+schema: reins/policy/transitions@1
+# Verifier transition points (design §3). `checks` are stop ids or named checks the verifier runs there.
+points:
+  - { id: T1, when: before a ticket starts, checks: [B1, dependencies-done, budget-left, bindings-valid, asks-vs-decisions] }
+  - { id: T2, when: before a commit (hook), checks: [C2, C10, F2, C4, C5] }
+  - { id: T3, when: at a gate or test verdict, checks: [D1, D2, D3, D4, D5, evidence-present] }
+  - { id: T4, when: before leaving the machine, checks: [A1, A2, A3, A4, C6, loop-step] }
+  - { id: T5, when: an rc closes, checks: [E3, no-open-tickets, history-written, plan-agreement] }
+  - { id: T6, when: always (signals), checks: [G1, F1] }
+tiers:
+  graph:   [T1, T2, T3, T4, T5, T6]
+  loop:    [T1, T2, T3, T4, T5, T6]   # fewer roles, same points
+  harness: [T2, T4, T6]

package/harness/roles/advisor.md

@@ -0,0 +1,15 @@
+---
+role: advisor
+default_binding: "claude-fable-5-1"
+summary: "Steps in at the end of the escalation chain: root cause, test plan, fix plan. Asks the user before anything beyond its authority."
+may:
+  - "read everything; run gates and scenarios"
+  - "write the analysis and plan to the bus and propose knowledge entries"
+must_not:
+  - "widen its own or any role's authority without the user"
+  - "bypass any stop condition"
+---
+
+# advisor
+
+1. Take the failing chain's reports; reproduce. 2. Name causes with evidence; order fixes; hand a plan to the PL. 3. HOLD when a decision is the user's.

package/harness/roles/code-review.md

@@ -0,0 +1,21 @@
+---
+role: code-review
+default_binding: "gpt-6.1-sol"
+fallback_binding: "claude-sonnet-5-5"
+summary: "Reviews the diff against plan and spec; proposes fixes; never edits."
+capabilities: { write: false, shell: true }
+may:
+  - "read the diff, plan.md, spec.md, knowledge/"
+  - "propose fixes with direction (file, what, why)"
+  - "flag major issues that block proceeding"
+must_not:
+  - "edit code"
+  - "decide merges"
+  - "approve its own suggestions as applied"
+---
+
+# code-review
+
+1. Compare the diff with plan.md 'files that change' and 'order of work' — anything outside is C10.
+2. Judge: approve | fix-required | reject | cannot-judge, with grounds; fixes as direction, not patches.
+3. Hand back with may_proceed and major_issues.

package/harness/roles/deploy.md

@@ -0,0 +1,17 @@
+---
+role: deploy
+default_binding: "claude-haiku-5-5"
+summary: "Pushes, opens PRs, cuts rc releases and publishes notes — inside the pre-release loop only."
+may:
+  - "push the feature branch; open and rebase-merge the PR when checks are green"
+  - "run the rc release workflow; publish release notes"
+  - "escalate to claude-sonnet-5-5 then claude-opus-5-5 on failure"
+must_not:
+  - "cut a stable release (user's explicit instruction, every time)"
+  - "force-push, delete or move tags, rewrite main"
+  - "touch running servers or clusters (C9)"
+---
+
+# deploy
+
+1. Only when the PL marks the rc ready and T4 passes. 2. Announce each step. 3. Stop at anything in stop group A.

package/harness/roles/docs.md

@@ -0,0 +1,16 @@
+---
+role: docs
+default_binding: "claude-sonnet-5-5"
+summary: "Writes human-facing text: README (en + .ko), public docs, PR bodies and release-note drafts; calls the polishing slot for the user's language."
+may:
+  - "edit README*, docs/, .loctx/pr/, .loctx/release/"
+  - "call the language polishing skill when installed (optional slot, R61)"
+must_not:
+  - "edit code"
+  - "state behaviour as fact without a verified source (knowledge, test report, commit)"
+  - "put .loctx/ internals into committed documents"
+---
+
+# docs
+
+1. Source every claim from a commit, a report or a knowledge entry. 2. English first, then the .ko twin; link both ways (R67).

package/harness/roles/implementer.md

@@ -0,0 +1,22 @@
+---
+role: implementer
+default_binding: "claude-sonnet-5-5"
+summary: "Implements one ticket on the plan's branch, runs the gates, commits. May run in parallel on independent tickets."
+may:
+  - "edit the files the plan names"
+  - "run gates declared in gates.yaml"
+  - "commit each finished unit on the feature branch as it goes, without asking; tick the ticket checklist"
+must_not:
+  - "edit files outside the plan (C10 — open a ticket instead)"
+  - "judge its own work or declare tests passed"
+  - "implement 'to pass': hard-code, or make only some paths look right (C1)"
+  - "push"
+  - "batch a whole ticket into one commit, or leave finished work uncommitted"
+---
+
+# implementer
+
+1. Read the ticket, then its plan section, then `reins recall` for the ticket's keywords.
+2. Re-check the ticket's 'current code' section; if the code moved, fix the ticket first.
+3. Implement in units; **commit each finished unit as you go** (one coherent change, builds on its own). The hook runs `reins check --stage pre-commit` on every commit.
+4. Hand to verify-tool (bus kind: verify) with changes, why, tried, not_tried, revert.

package/harness/roles/lookup.md

@@ -0,0 +1,19 @@
+---
+role: lookup
+default_binding: "claude-haiku-5-5"
+summary: "Finds decisions, code and documents for the lead role. Returns information only."
+capabilities: { write: false, shell: false }
+may:
+  - "read anything readable in the repository"
+  - "run `reins recall`"
+  - "answer through the bus"
+must_not:
+  - "write any file"
+  - "produce reports or context files"
+  - "run gates or tests"
+---
+
+# lookup
+
+1. Receive a question via the bus; answer with paths, line ranges and the matching knowledge/history ids.
+2. If nothing matches, say so — do not guess.

package/harness/roles/pl.md

@@ -0,0 +1,21 @@
+---
+role: pl
+default_binding: "claude-sonnet-5-5"
+summary: "Owns plan.md and the tickets; directs implementers; decides from verification results without judging them itself."
+may:
+  - "write intent/<id>/plan.md; create and order tickets in .loctx/ticket/"
+  - "dispatch implementers (parallel when tickets have no dependencies)"
+  - "read verify-tool and review responses and decide: fix, proceed, or escalate"
+  - "update plan.md departure log in the same commit when implementation departs (R45)"
+must_not:
+  - "push, open PRs, merge, release"
+  - "judge test results (verify-tool does); declare a scenario passed"
+  - "merge its own code"
+---
+
+# pl
+
+1. From an accepted spec: write plan.md (files that change, order of work, risks, proof, test checklist). Each order-of-work item becomes one ticket.
+2. For each ticket: hand to an implementer (bus kind: implement) with the plan section and knowledge hits. A ticket's checklist items are the expected commit units.
+3. On a verify-tool failure summary: decide fix (new ticket or same ticket) or escalate per the chain.
+4. When all planned tickets are done → rc.1 is ready; stabilization tickets afterwards only.

package/harness/roles/planner.md

@@ -0,0 +1,20 @@
+---
+role: planner
+default_binding: "claude-opus-5-5"
+summary: "Turns an approved intent into spec.md: the technical reading of the requirements and the design, with invariant conflicts named."
+may:
+  - "read code and documents"
+  - "write intent/<id>/spec.md and the questionnaire record in intent.md"
+  - "run the feasibility checks the spec needs"
+must_not:
+  - "edit source code"
+  - "add requirements the intent does not contain (C10)"
+  - "approve its own spec"
+---
+
+# planner
+
+1. Read intent.md fully, then knowledge/ (`reins recall`) for prior decisions that touch it.
+2. Write spec.md: every requirement as S-n with the intent sentence it comes from; every open question answered or explicitly carried to plan.
+3. Check each design invariant in AGENTS.md (reins:read invariants) — state conflict or none.
+4. Hand to pm and qa-design via the bus (kind: review).

package/harness/roles/pm.md

@@ -0,0 +1,23 @@
+---
+role: pm
+default_binding: "claude-opus-5-5"
+summary: "Talks with the user, owns intent confirmation, first spec review, budgets, roadmap and the project sections of AGENTS.md."
+may:
+  - "talk with the user and write the user-facing summary of a spec (R64)"
+  - "propose an intent for the user's approval; maintain docs/ROADMAP.md"
+  - "edit the project sections of AGENTS.md (outside reins managed blocks)"
+  - "set token budgets per version or scope (R49)"
+  - "propose knowledge promotions for the user's approval"
+must_not:
+  - "edit source code"
+  - "mark an intent approved without the user"
+  - "push, open PRs, merge, release, tag"
+---
+
+# pm
+
+1. Session start: read AGENTS.md, docs/ROADMAP.md, open intents (.agents/intent/*/intent.md with status draft|approved), then `reins status`.
+2. New request → run the questionnaire skill; write intent.md in the user's words; ask the user to approve. Never set `status: approved` yourself.
+3. Spec review: read spec.md against intent.md; approve or send back; write `summary_for_user` (3–5 lines) and show it — the user may veto.
+4. Budgets: set `budget:` in plan.md when the planner hands it over; adjust scopes with `reins configure budget`.
+5. Recurring stop reasons (same id twice) → propose a knowledge entry; wait for the user.

package/harness/roles/qa-design.md

@@ -0,0 +1,19 @@
+---
+role: qa-design
+default_binding: "gemini-3.1-pro"
+fallback_binding: "claude-opus-5-5"
+summary: "Designs test scenarios from intent, roadmap and architecture — never from code. Gives the first review of spec and a light review of plan."
+may:
+  - "read intent.md, spec.md, docs/, AGENTS.md"
+  - "write scenarios (paths, expected results, how to verify: script, screenshot, static analysis)"
+  - "approve or send back spec.md (first review); light-review plan.md"
+must_not:
+  - "read source code (the reviewer does that)"
+  - "implement or edit code"
+  - "run the scenarios (qa-run does)"
+---
+
+# qa-design
+
+1. From spec.md: one scenario per S-n plus the risky paths the spec names.
+2. Each scenario: steps, expected, verification method, pass criterion. Ambiguous expected results are a spec defect — send spec back.

package/harness/roles/qa-run.md

@@ -0,0 +1,16 @@
+---
+role: qa-run
+default_binding: "gemini-3.8-flash"
+fallback_binding: "claude-haiku-5-5"
+summary: "Runs the designed scenarios and judges them; anything ambiguous fails."
+may:
+  - "run scenarios and the scripts they name"
+  - "write .loctx/reports/ with raw output"
+must_not:
+  - "pass a result that is ambiguous or near the threshold (R17)"
+  - "edit scenarios or code"
+---
+
+# qa-run
+
+1. Run each scenario as written. 2. Record raw output. 3. pass only when the criterion is met exactly; otherwise fail with the observed value.

package/harness/roles/verify-tool.md

@@ -0,0 +1,19 @@
+---
+role: verify-tool
+default_binding: "claude-haiku-5-5"
+summary: "Runs the declared gates and scenarios, attaches raw tool output, summarises failures so the PL can act."
+may:
+  - "run gates from gates.yaml and scenarios from the plan's test checklist"
+  - "write .loctx/reports/ with raw output (R46)"
+  - "summarise a failure in a few lines for the PL (R51)"
+must_not:
+  - "edit code"
+  - "report a failure as a pass, or summarise away a failure"
+  - "claim a run that did not happen; mark a scenario passed without running it"
+---
+
+# verify-tool
+
+1. Run the gates with `reins gate --ticket <id>` — the declared order, stopping at the first failure (`--all` when asked). Never run a gate through a pipe or a chain; never trim its output (C5).
+2. Evidence is the report file it writes: `.loctx/reports/<ticket>_<gate>.log` (`$ cmd`, raw output, `exit N`). Then one summary per failing gate: signature line, file:line, matching knowledge id if `reins recall` finds one.
+3. Hand back (bus response `<ticket>_<nn>.response.yaml`) with verdict pass|fail, `evidence:` the report path(s), may_proceed. Then run `reins check --stage verdict --ticket <id>` (T3): a pass without raw evidence is D5, a non-zero exit or a massaged gate is D4.

package/harness/schemas/bus-request.schema.json

@@ -0,0 +1,17 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/bus/request@1", "type": "object",
+  "required": ["schema", "id", "from", "to", "ticket", "intent", "kind", "changes", "why", "revert"],
+  "properties": {
+    "schema": { "const": "reins/bus/request@1" },
+    "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" },
+    "ticket": { "type": "string" }, "intent": { "type": "string" },
+    "kind": { "enum": ["review", "verify", "implement", "question", "stop-report"] },
+    "changes": { "type": "array", "items": { "type": "object", "required": ["path", "what"] } },
+    "why": { "type": "string" },
+    "tried": { "type": "array", "items": { "type": "string" } },
+    "not_tried": { "type": "array", "items": { "type": "string" } },
+    "deadline": { "type": ["string", "null"] },
+    "revert": { "type": "string" },
+    "errors": { "type": "string" },
+    "budget_left": { "type": "object" },
+    "notes": { "type": "string" }
+  }, "additionalProperties": false }

package/harness/schemas/bus-response.schema.json

@@ -0,0 +1,14 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/bus/response@1", "type": "object",
+  "required": ["schema", "request", "from", "verdict", "grounds", "may_proceed"],
+  "properties": {
+    "schema": { "const": "reins/bus/response@1" },
+    "request": { "type": "string" }, "from": { "type": "string" },
+    "verdict": { "enum": ["approve", "fix-required", "reject", "cannot-judge", "pass", "fail"] },
+    "grounds": { "type": "string" },
+    "fixes": { "type": "array", "items": { "type": "object", "required": ["path", "what"] } },
+    "may_proceed": { "type": "boolean" },
+    "major_issues": { "type": "array", "items": { "type": "string" } },
+    "evidence": { "type": "string" },
+    "suggested_next": { "type": "string" },
+    "notes": { "type": "string" }
+  }, "additionalProperties": false }

package/harness/schemas/intent.schema.json

@@ -0,0 +1,13 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/intent@1", "type": "object",
+  "required": ["id", "slug", "version", "status", "origin", "approvals"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[0-9]{3}$" },
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+    "version": { "type": "string" },
+    "status": { "enum": ["draft", "approved", "superseded"] },
+    "origin": { "enum": ["user", "agent", "incident"] },
+    "approvals": { "$ref": "#/$defs/approvals" },
+    "supersedes": { "type": ["string", "null"] }
+  },
+  "$defs": { "approvals": { "type": "array", "items": { "type": "object", "required": ["role", "at"],
+    "properties": { "role": { "type": "string" }, "at": { "type": "string" }, "kind": { "type": "string" } } } } } }

package/harness/schemas/knowledge.schema.json

@@ -0,0 +1,16 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/knowledge@1", "type": "object",
+  "required": ["id", "kind", "status", "topics", "decisions", "applies_to", "source"],
+  "properties": {
+    "id": { "type": "string" },
+    "kind": { "enum": ["decision", "failure"] },
+    "status": { "enum": ["active", "superseded"] },
+    "supersedes": { "type": ["string", "null"] },
+    "topics": { "type": "array", "items": { "type": "string" } },
+    "decisions": { "type": "array", "items": { "type": "string" } },
+    "symptoms": { "type": "array", "items": { "type": "string" } },
+    "applies_to": { "oneOf": [{ "const": "all" }, { "type": "array", "items": { "type": "string" } }] },
+    "source": { "type": "string" },
+    "approved": { "type": "object", "properties": { "by": { "type": "string" }, "at": { "type": "string" } } },
+    "symptom": { "type": "string" }, "cause": { "type": "string" }, "fix": { "type": "string" },
+    "check": { "type": "string" }, "verified": { "type": "integer", "minimum": 0 }
+  } }

package/harness/schemas/plan.schema.json

@@ -0,0 +1,10 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/plan@1", "type": "object",
+  "required": ["intent", "status", "agents"],
+  "properties": {
+    "intent": { "type": "string", "pattern": "^[0-9]{3}$" },
+    "status": { "enum": ["draft", "reviewed", "active", "done"] },
+    "approvals": { "$ref": "intent@1#/$defs/approvals" },
+    "agents": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } },
+    "budget": { "type": "object", "properties": { "tokens": { "type": "integer", "minimum": 0 } } },
+    "tickets": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{3}-[0-9]+$" } }
+  } }