@bluenyang/reins 0.0.0-stage → 0.1.0

package/harness/schemas/spec.schema.json

@@ -0,0 +1,8 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/spec@1", "type": "object",
+  "required": ["intent", "status", "approvals"],
+  "properties": {
+    "intent": { "type": "string", "pattern": "^[0-9]{3}$" },
+    "status": { "enum": ["draft", "reviewed", "accepted", "rejected"] },
+    "approvals": { "$ref": "intent@1#/$defs/approvals" },
+    "summary_for_user": { "type": "string", "maxLength": 600 }
+  } }

package/harness/schemas/ticket.schema.json

@@ -0,0 +1,15 @@
+{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "reins/ticket@1", "type": "object",
+  "required": ["id", "intent", "plan_step", "title", "status", "release", "role"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[0-9]{3}-[0-9]+$" },
+    "intent": { "type": "string", "pattern": "^[0-9]{3}$" },
+    "plan_step": { "type": "integer", "minimum": 1 },
+    "title": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["todo", "doing", "blocked", "done"] },
+    "depends": { "type": "array", "items": { "type": "string" } },
+    "release": { "enum": ["planned", "stabilization"] },
+    "role": { "type": "string" },
+    "budget": { "type": "object", "properties": { "tokens": { "type": "integer", "minimum": 0 } } },
+    "asks": { "type": "array", "items": { "type": "string" } },
+    "branch": { "type": "string" }
+  } }

package/harness/templates/agents-md-blocks.md

@@ -0,0 +1,26 @@
+<!-- reins:begin notice v=0.1.0 -->
+> The blocks marked `reins:begin … reins:end` in this file are generated by reins from `.agents/harness/`. Do not edit them by hand; run `reins update`. Everything outside the blocks belongs to the project.
+<!-- reins:end notice -->
+
+<!-- reins:begin workflow v=0.1.0 -->
+## Workflow
+
+- Session start: `AGENTS.md` → `docs/ROADMAP.md` → open intents in `.agents/intent/` → `reins status`.
+- Work comes from `.loctx/ticket/`; one file is one item; delete it when done after writing a line in `.loctx/history/`.
+- **Committing is part of doing the work.** Land each finished unit — one coherent change that builds on its own — as its own local commit as you go, on the feature branch. Do not batch a whole ticket into one commit, and do not wait for permission to commit locally. Never commit on the default branch; never bypass hooks.
+- Before a non-trivial decision: `reins recall <keyword>` (knowledge, history, symptoms).
+- The verifier runs at every transition (`reins check`). Verdicts: CONTINUE · HOLD (ask the user) · STOP (recorded, resumable) · ESCALATE. A stop names its reason id (A1–G2).
+- Anything that leaves the machine happens only in the deploy role inside the pre-release loop, or on the user's explicit instruction.
+<!-- reins:end workflow -->
+
+<!-- reins:begin skills v=0.1.0 -->
+## Skills
+
+See `.agents/SKILLS.md`. Skills that push, merge or release are user-invoked only.
+<!-- reins:end skills -->
+
+<!-- reins:begin language v=0.1.0 -->
+## Language
+
+`AGENTS.md`, code, commits, `.agents/` sources: English. Documents the user reads (`intent/`, `.loctx/`, `docs/*.ko.md`): the project's user language.
+<!-- reins:end language -->

package/harness/templates/bus/request.yaml

@@ -0,0 +1,14 @@
+schema: reins/bus/request@1
+id: 000-1_01
+from: pl
+to: implementer
+ticket: 000-1
+intent: "000"
+kind: implement
+changes: []
+why: ""
+tried: []
+not_tried: []
+deadline: null
+revert: ""
+errors: ""

package/harness/templates/bus/response.yaml

@@ -0,0 +1,9 @@
+schema: reins/bus/response@1
+request: 000-1_01
+from: implementer
+verdict: pass
+grounds: ""
+fixes: []
+may_proceed: true
+major_issues: []
+evidence: ""

package/harness/templates/intent.md

@@ -0,0 +1,23 @@
+---
+id: "000"
+slug: example
+version: 0.0.0
+status: draft
+origin: user
+approvals: []
+supersedes: null
+---
+## 문제
+—
+## 바라는 결과
+—
+## 영향 범위
+—
+## 제약
+—
+## 열린 질문
+—
+## 질의서 기록
+—
+## 하지 않을 것
+—

package/harness/templates/knowledge.md

@@ -0,0 +1,20 @@
+---
+id: YYYY-MM-DD_slug
+kind: decision
+status: active
+supersedes: null
+topics: []
+decisions: []
+symptoms: []
+applies_to: all
+source: —
+approved: { by: user, at: YYYY-MM-DD }
+---
+## 결정
+—
+## 이유
+—
+## 적용
+—
+## 바뀌면
+—

package/harness/templates/plan.md

@@ -0,0 +1,23 @@
+---
+intent: "000"
+status: draft
+approvals: []
+agents:
+  implement: [implementer]
+  verify: [verify-tool]
+  review: [code-review]
+budget: {}
+tickets: []
+---
+## 바뀌는 파일
+—
+## 작업 순서
+1. — (S-1)
+## 위험
+—
+## 증명
+—
+## 테스트 체크리스트
+—
+## 이탈 기록
+—

package/harness/templates/spec.md

@@ -0,0 +1,17 @@
+---
+intent: "000"
+status: draft
+approvals: []
+summary_for_user: |
+  —
+---
+## 요구 해석
+- S-1 —
+## 설계
+—
+## 우려 표시
+—
+## 검증 기준
+—
+## 범위 밖
+—

package/harness/templates/ticket.md

@@ -0,0 +1,29 @@
+---
+id: 000-1
+intent: "000"
+plan_step: 1
+title: —
+status: todo
+depends: []
+release: planned
+role: implementer
+budget: {}
+asks: []
+branch: feat/000-example
+---
+## 목적
+—
+## 현재 코드
+—
+## 작업
+- [ ] —
+## 결정
+—
+## 기대 결과
+—
+## 예상 오류 / 주의
+—
+## 검증
+- [ ] 게이트
+- [ ] 시나리오
+- [ ] 사용자 확인 필요

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@bluenyang/reins",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Installs, migrates and updates an agent harness (harness → loop → graph) that keeps coding agents inside their permitted roles.",
+  "license": "MIT",
+  "repository": "github:bluenyang/reins",
+  "type": "module",
+  "bin": {
+    "reins": "cli/dist/reins.js"
+  },
+  "files": [
+    "cli/dist",
+    "harness",
+    "skills",
+    "README.md",
+    "docs/README.ko.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@12.15.0",
+  "scripts": {
+    "build": "tsc -p cli/tsconfig.json",
+    "typecheck": "tsc -p cli/tsconfig.json --noEmit",
+    "lint": "oxlint cli/src cli/test test",
+    "fmt": "oxfmt --write cli/src cli/test test",
+    "fmt:check": "oxfmt --check cli/src cli/test test",
+    "test": "vitest run",
+    "check": "pnpm lint && pnpm fmt:check && pnpm typecheck && pnpm test",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "commander": "^15.0.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}

package/skills/reins-intent/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: reins-intent
+description: Turn a request into an approved intent and an accepted spec — runs the questionnaire with the user, writes .agents/intent/NNN_slug/intent.md, holds for the user's approval, then has the planner write spec.md and shows its summary for the user's veto. Use when the user brings a new feature, change or problem, says new intent or plan this, or before any spec, plan or code exists for the work.
+---
+
+# reins-intent
+
+The two points where a person decides (design §4): **the intent is approved by the user**, and **the spec
+summary may be vetoed by the user** (R64). Everything here leads to one of them; never cross either alone.
+
+## Intent — pm role
+1. Search what was already decided or rejected: `reins recall <keywords>` (until it ships:
+   `grep -l 'decisions:.*<keyword>' .loctx/history/*` and `.agents/knowledge/`). A rejected proposal is not
+   raised again (C8).
+2. Next id = highest `.agents/intent/NNN_*` + 1, three digits; slug in kebab-case.
+3. **Questionnaire — ask only what only the user knows**, in one batch: the problem, the desired outcome,
+   constraints, what not to do. State your defaults for everything else instead of asking.
+4. Copy `.agents/harness/templates/intent.md` to `.agents/intent/<NNN>_<slug>/intent.md`; write it in the
+   user's words and language; record the questions and answers under the questionnaire section;
+   `status: draft`, `origin: user`, `version:` the release it targets.
+5. Show it and **ask for approval. Never set `approved` yourself.** On the user's explicit yes:
+   `status: approved`, `approvals: [{role: user, at: <date>}]`, and commit only that change with the trailer
+   `Approved-by: <the user's name>` (`git commit -m "docs(intent): approve <NNN> <slug>" -m "Approved-by: …"`).
+
+## Spec — planner, then pm and qa-design
+6. planner: copy `templates/spec.md`; every requirement is `S-n` with the intent sentence it comes from;
+   invariants in AGENTS.md checked (conflict or none); `summary_for_user:` 3–5 lines in the user's language.
+7. pm reviews against the intent; qa-design gives the first review (bus `kind: review`). Fix, then
+   `status: reviewed`.
+8. **Show `summary_for_user` and the acceptance criteria; the user may veto** (G2 → revise the spec). No veto →
+   `status: accepted`, `approvals:` pm, qa-design and `{role: user, kind: summary}`; commit with
+   `Approved-by:`. Then hand over to `reins-loop`.
+
+A role bound to a vendor with no generated files yet (round one generates Claude only) runs on Claude with
+its role file as instructions; say so in the history line.

package/skills/reins-loop/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: reins-loop
+description: Run an accepted spec through the reins loop — plan, tickets, implement, verify, review, history — calling reins check at every transition (T1 ticket-start, T2 pre-commit, T3 verdict, T5 rc-close) and stopping where it says. Use when an intent's spec is accepted, when the user says continue, next ticket or run the loop, or to resume a stopped ticket.
+---
+
+# reins-loop
+
+Roles judge, scripts enforce. After every step run the named check; **its verdict decides what happens next**:
+CONTINUE → go on · HOLD → ask the user (one line: reason id + what you need) · STOP → do what `resume` says,
+then re-run the same check · ESCALATE → the next role in the chain (pl → pm → advisor → user).
+Exit codes 0/10/20/30. Use `npx @bluenyang/reins` (inside the reins repository: `node cli/dist/reins.js`).
+
+## Plan — pl
+1. From the accepted spec: copy `templates/plan.md` to the intent folder — files that change, **order of work
+   (one item = one ticket)**, risks, proof, test checklist; `tickets: [<NNN>-1, …]`, `agents:` roles.
+2. qa-design reviews it lightly (bus `kind: review`) → `status: reviewed`. Commit.
+3. For each order-of-work item: `.loctx/ticket/<NNN>-<n>_<slug>.md` from `templates/ticket.md`. Anything
+   the ticket cannot decide alone goes in `asks:`.
+
+## Each ticket
+4. **T1** `reins check --stage ticket-start --ticket <id>`. Open `asks:` hold for the user; the check also
+   names recorded decisions that may already answer them.
+5. Branch `type/<NNN>-<slug>` from the default branch. implementer (`reins-implementer` subagent):
+   ticket → plan section → `reins recall` → implement, **one commit per finished unit** (the hook runs **T2**).
+   A diff outside the plan updates plan.md's departure log in the same commit (C2), or opens a new ticket (C10).
+6. **Verify.** Write `.loctx/bus/<id>_<nn>.request.yaml` (`kind: verify`); verify-tool runs
+   `reins gate --ticket <id>` and answers in `<id>_<nn>.response.yaml` with the report paths as `evidence:`.
+   **T3** `reins check --stage verdict --ticket <id>`. Fail → back to 5 (a second failure escalates, D1).
+7. **Review.** code-review gets the diff against plan and spec (`kind: review`) and proposes fixes only;
+   pl decides fix or proceed. Nobody judges their own work.
+8. **Close.** `status: done`; one history page or line in `.loctx/history/` naming the ticket id, its commits,
+   and a `decisions:` line; then delete the ticket file and its bus files.
+
+**Metrics.** After each role run, report what it cost: `reins metrics record --role <r> --tokens <n> --ticket <id>`.
+Tokens come from the vendor — Claude subagent: the Agent result's token count · `codex exec`: the "tokens used"
+line · `agy`, `cursor-agent` with `--output-format json`: the usage field when present. No count from the
+vendor → record nothing, never guess. `reins check` and `reins gate` log themselves to
+`.loctx/reports/metrics.jsonl`; `reins metrics` summarises it.
+
+## Release
+9. When every planned ticket is done: **T5** `reins check --stage rc-close --release <version>`. Report to
+   the user. Push, PR and release happen only on the user's instruction, in the deploy role (T4 runs in the
+   pre-push hook); a stable release is always the user's explicit call (A2).
+
+On an interruption (G1) write where you are — ticket, step, last commit, open bus files, next command — to
+the ticket, so the same command resumes.

package/skills/reins-setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: reins-setup
+description: Install reins in this repository, or move an existing harness onto it — detects the harness generation, runs reins install or reins migrate, confirms gates, bindings and hooks with the user, and checks for drift. Use when the user asks to set up, install, adopt or migrate to reins, or when AGENTS.md has no reins blocks yet.
+---
+
+# reins-setup
+
+You act as the **pm** role (`.agents/harness/roles/pm.md` once installed). The CLI does the work; you collect
+the answers only the user can give and report what happened. Run the CLI as `npx @bluenyang/reins …`
+(inside the reins repository itself: `node cli/dist/reins.js …`).
+
+1. **Look first.** `reins install graph --dry-run --json` → read `generation` and `refused`.
+   - `refused` (3rd/4th-generation harness) → `reins migrate <tier> --dry-run` and show the moves.
+   - `.ai/` present (1st/2nd generation) → install, then offer `reins migrate`.
+2. **One batch of questions, defaults stated** — never more than one round:
+   tier (`graph` when two or more vendors are detected, else `loop`; `harness` for permissions only) ·
+   vendors to use (show the detected ones) · language of the documents the user reads · public repository?
+3. **Apply** non-interactively: `reins install <tier> --mode auto` (or `reins migrate <tier> --mode auto`).
+   Then adjust what the user changed: `reins configure bindings --set <role>=<model> …`.
+4. **Gates.** Show `.agents/harness/gates.yaml`; run `reins gate` once. A gate that fails or mutates files is
+   the user's call — never edit the project's scripts to make it pass.
+5. **Hooks are proposed, not added.** Show the proposal from the install notes; only on the user's yes run
+   `reins install <tier> --mode auto --hooks`.
+6. **Verify.** `reins check --drift` must print `drift: ok`. Commit on a branch (`chore/reins-setup`), one commit
+   per step that changed files. Never push.
+7. **Report** in the user's language: generation before → after, the bindings table, gates, notes, and the
+   next step — bring the first request to `reins-intent`.